PFC Programmer's Reference Manual, Appendix J - pfc_w_master

Exclusive Excerpt from PFC Programmer's Reference Manual, by Rik Brooks

Appendix by Sharon Weinstrom Buntz

What is pfc_w_master?

pfc_w_master is the Top-Most Ancestor of ALL windows in the PFC;
"Great, Great Grandpa" of ALL PFC Windows.

Think about that for a minute…

That means that there is a family tree for five generations (at least),
and so there are a lot of family members under Great, Great Grandpa!

Figure 1 - pfc_w_master is the "Great, Great Grandpa" of ALL PFC Windows

Using the PFC, ALL of your windows will descend from pfc_w_master.
So that means that every single window in your application is affected by what pfc_w_master does.

All of the main "plumbing" of the PFC’s "framework" is included in pfc_w_master. It has to be there for the PFC to work properly, re-routing events of the window to all of the proper services, other visual objects or other pfc_w_master events. By the way, if you aren’t yet familiar with the concept of "Service-based Architecture", it would be a good idea to read up on it. Two good sources for this are:

Powersoft’s white paper on PFC	http://www.powersoft.com/products/devtools/pb50/pfcarch.html#overview
William T. Green’s white paper on SBA	http://www.concentric.net/~Bgcastle/SBA/SBA_Main.html

Next down the chain of ancestry from pfc_w_master is w_master. W_master is pfc_w_master’s direct descendant, the only direct descendant in fact.

Continuing down from w_master, then descend all of the different types of windows, such as a Frame, a Sheet, a "Main SDI" window, a Response window and so on. There are six of them. Take a look at them in Figure 2. Notice how the descendants from w_master are "higher-level" PFC-level pfc_w_ objects, not just PFE-level w_ objects. Then come the w_<6 types> objects, the ones from which you will inherit all of your application-specific windows. These are w_frame, w_sheet, w_main, w_response, w_popup and w_child.

Figure 2 - pfc_w_master è w_master è six window type descendants from which you will inherit
This picture was derived from PowerBuilder’s native Browser Output Documentation… Try it out by pressing the PowerBuilder PowerBar toolbar.

Note Take notice how the PFC/PFE/PFC/PFE objects spiral has you walk down the chain of inheritance. Although we will not go into this in detail, it is important to realize this early on. This is so that you can understand the regeneration implications of the PFC objects being inherited from the PFE objects (which normally sounds backwards).

Why understand pfc_w_master?

As a PFC programmer, all of your windows will always be descendants of pfc_w_master. (You should never inherit directly from the PowerBuilder Window type in a PFC application.) This is because PFC needs all of the "plumbing" for the PFC "framework" that is provided in pfc_w_master in all of its windows in order to work properly. And that is why it is so important to understand pfc_w_master. Because from him all of your PFC windows descend, and he drives all of the PFC’s objects and main processes..

Understand pfc_w_master, and you shall understand a lot about the PFC and how to manage all of your windows!

Which of these six window type descendants of pfc_w_master do I inherit from?

You will always inherit from one of these six window type descendants (or lower) of pfc_w_master: w_frame, w_sheet, w_main, w_response, w_popup or w_child. The type that you select depends on the type of window you want for that particular situation.

If you are using MDI (Multiple Document Interface ~ like PowerBuilder itself does), then w_frame is the MDI frame ancestor, and your application's frame w_<your app>_frame will inherit from him. And w_sheet is the ancestor from which each of your frame's MDI sheets will be inherited from, for example w_se_transcript_maint.

If you are not using MDI, but rather SDI (Single Document Interface), where you don't need a frame with lots of sheets within it, then you would inherit from w_main rather than w_sheet for each of your main windows.

From either your MDI or SDI application, for other types of windows, inherit from either w_response, w_popup or w_child.

So basically, every time you open the Window Painter to create a new application window, you will select "Inherit", and then you will select one of these six windows to inherit from - w_frame, w_sheet, w_main, w_response, w_popup and w_child. You may have a need to inherit from a lower level down, but just realize that you will never inherit directly from either pfc_w_master, w_master or PowerBuilder’s native window objects.

Keep in mind, the PFC follows this same scheme with the ready-made windows that it comes with. So, the PFC itself contains some descendants of these six window type descendants. Take for example, w_logon, which is inherited from pfc_w_logon, which is inherited from w_response.

Figure 3 illustrates how to inherit from the six window type descendants for MDI apps and SDI apps. It also shows how the PFC itself contains some descendants from these six window type descendants. Here we are using "se_***" as our naming convention for our application objects.

Figure 3 - You should inherit from these six window types, such as w_frame è w_se_frame for an MDI frame.
Note that there are already some PFC objects descending from these, such as w_response è pfc_w_logon è w_logon.

Would I ever customize my pfc_w_master?

Probably not. You will probably never customize or change pfc_w_master. This is because you should almost never change the PFC-level source directly yourself. Here are some reasons why…

1. For one, it will throw Powersoft’s customer support for a loop. It is probably even written in the support contract that they will not support you if you do so.

2. Secondly, sticking to the base will benefit you because then you are in tune with all of the other PFCers out there. So everyone is on the "same page". Also, then you may easily take advantage of other PFC extensions written by others.

3. Thirdly, you would normally take advantage of the PFE layer to enhance or correct the PFC level objects. That is why the PFE layer is there, that is its purpose. (Please see the next section for details.)

So only new releases of the PFC would change (actually replace) your PFC PBLs.

Now having said all that, there is one exception to this golden rule. You may want to change the PFC-layer source code directly if a PFC release has already come out with a known, existing, official fix, and you have not yet migrated to that version. (Later, we will show you two specific cases of these, under Bug Alert!) Or perhaps Powersoft has announced a patch or such.

In any case, you would want to document profusely just exactly what you had changed (see Note below). This is because you would want to double-check or re-implement any changes that you make to the PFC objects after installing the new version of the PFC objects. Remember, new releases replace your PFC PBLs. And remember, these cases where you change the PFC objects directly should be rare anyway.

Would I ever customize my w_master?

Yes, there are a couple of cases where you may want to customizew_master.

Note Let’s add up front, that you should document profusely any changes that you make to w_master, in the actual object (preferably with a standard comment that you copy and paste from say a global function), and in an external document. This goes for w_master as well as any other PFE level object that you might enhance. This will help you incorporate future PFC releases. Another helpful tip on remembering to which PFE objects that your company has actually made changes, is to keep those objects in a separate PBL. So when you modify a PFE object, you would remove it from your regular PFE PBL, and add it to your extra PFE PBL.

1. First case, you might change w_master if you were enhancing the PFC code in pfc_w_master, or making a temporary fix to the pfc_w_master code. In these cases, you would be either extending the pfc_w_master code, overriding the pfc_w_master code, or possibly adding new instance variables, new window functions or new user events. Which leads us to the second case…

2. And, secondly, you may have a need to create one or more "empty, placeholder, virtual" events yourself, modeled after how the PFC is designed and written. So you would define these user events in w_master. But still, even in this case, consider whether you really want these new empty events for all of your windows, rather than just a subset, or only for special case application windows. This is because events "fail silently", so they don’t actually have to exist on a window that does not need the special event. But there may be cases where you would want to cover all windows…

For example, perhaps you are in an environment where you always have some particular master or offline process to alert (via a special table) before and after performing your updates, that contains information about your updates.

In this case one might add pre-update and post-update user events to w_master for processes that fall within the Logical Unit of Work processing (as the PFC events that are already there, are processed outside of the database transaction). You might call these new events, say, (ue_PreUpdateInLUW and ue_PostUpdateInLUW) or (ue_TranPreUpdate and ue_TranPostUpdate), just as some examples. It is discouraged to use the pfc_ prefix on your own added user events.

Then, of course, you would have to trigger them in the appropriate place. In our example, w_master’s pfc_update could be overridden, trigger the first new user event, call the ancestor’s event, and finally trigger the second new user event.

And now, all of your windows will have these empty events, ready to be extended in the appropriate descendants. And every window will know to execute them when the time comes.

We might add here though, that in thePFC 6.0 Release, the Save Process in the pfc_w_master will be dramatically enhanced. So be careful with any enhancements or changes that you make to the save process.

Other than those two cases though, usually you would not actually want to modify w_master directly. This is because any change that you make to w_master will affect ALL of your windows since w_master is the ancestor of all PFC windows (other than pfc_w_master). So keep in mind, whenever you add instance variables, events, and functions to w_master, the changes will impact all PFC windows. And so it follows that you should regenerate all of your windows immediately thereafter. To reemphasize the impact, when you regenerate all of your windows after adding new attributes and methods to w_master, you are affecting the compiled version of all of your windows, including the PFC-level objects. This is due to the spiraling dependancies between the PFC/PFE/PFC/PFE objects that we touched on in Figure 2 caption’s Note.

But, usually, rather than changing w_master, you would modify one of the six window type descendants (or lower) of pfc_w_master. For example, you would normally just want to change, say w_sheet, to add functionality to all of your sheets, not ALL of your windows.

Two Big Pictures of pfc_w_master

Let’s take one more look at the window hierarchy here in Figure 4 …

Figure 4 - Another viewpoint of the pfc_w_master relatives

And below, in Figure 5, here’s the "Big picture" from your PFC 5.0.03 Online Help. This is what we will cover in detail… We will be covering up through the 5.0.03 release with an indicator of 5.0.0# beside what is new since 5.0.00.

The changes in thePFC 6.0 Release are drastic enough (and not finalized as of this writing) to merit leaving them out of this section. It would actually confuse you more than it would help you to interweave them into here. So we will just focus on 5.0.0# versions. But don’t worry, to satisfy your curiosity, and to tie in where the PFC is going with 6.0, we will outline in detail what is projected for the PFC 6.0 Release in the last section. So, as hard as it is now to say with certainty what will actually be released in the next version, it is important to try ~ as you will probably be reading this after 6.0 is out.

Figure 5 - All about pfc_w_master - Check out the PFC Help Often

What does pfc_w_master contain?

Now that we see the big pictures, roll up your sleeves! It’s time to get down to the technical details and learn all about pfc_w_master…

pfc_w_master contains:

Instance variables to keep track of key information needed for the window,

such as flags, an array of all of the controls on the window which will be updated, a database error string, and all of the instances of the Window Services that are CREATEd when you call the window functions to turn them on.

Functions to access all of the Instance variables which areprotected,

as every good Object-Oriented program provides.
(By the way, there are no private instance variables in pfc_w_master.)

Functions to turn on and off the Window Services,

specifically the Basic Window Service, the Window Preference Service and the Window Resize Service. Please note that the Sheet Management Service and the Status Bar Service are included in pfc_w_master’s descendant, pfc_w_frame, not pfc_w_master itself.

Function to do pre-update checks…

The key of_UpdateChecks( ) function does an AcceptText( ) on all DataWindows, checks for pending updates, load an array of controls to update and perform validations.

Pre-codedNative PowerBuilder events

that automatically handle a lot of the functionality that is needed by all windows. Key native PowerBuilder events, such as the Open, CloseQuery, Close, Resize and Move events, already have PFC code in them to handle basic window processing logic. Most of the code simply "re-routes" the processing off to the proper Non-visual User Object which handles a particular Service’s processing. The CloseQuery is a KEY, important PFC event, so be sure to read up on it below. Also, realize that at the bottom of the Close event, the PFC automatically does some housekeeping for you to turn off (DESTROY) any window services which may have been turned on for that window.

Pre-coded and Partially-coded+Extendable PFC User Events

that automatically handle a lot of the functionality that is needed by all windows. Key PFC user events, such as the pfc_Save, pfc_MessageRouter, pfc_Help, pfc_MicroHelp, pfc_ControlGotFocus and pfc_Close events, already have PFC code in them to handle basic window processing logic. Some of them, like the Save event, spawns off a whole sequence of other pre-/extendable-/coded and "empty" events to automatically handle the flow of events for you. The pfc_MessageRouter "Message Router" is a special event that will go looking for an object which has a particular user event, and it will trigger the event on the object that it finds. Be sure to read up on the pfc_Save and the pfc_MessageRouter events, as they are KEY, important PFC events.

Note
Take note that on any Partially-coded+Extendable User Event… If you do have a need to "extend" the script for any of these events, you should first check the ancestor’s return code. I say "extend" because in order to check the ancestor’s return code (at least pre-PowerBuilder 6.0), you must override the ancestor script. At any rate, it is important to check the ancestor’s return code because there is already script in the PFC’s ancestor code, and it may fail.

The most common events in this category that PFCers sometimes "extend" are:

pfc_AcceptText
pfc_PostUpdate
pfc_Update
pfc_UpdatesPending
pfc_Validation

These events are often extended in order to have them recognize other controls such as the ListView and TreeView controls… However, please note…
Note: In thePFC 6.0 Release, rather than having to extend these events to recognize such controls as the ListView and TreeView, you may take advantage of the new Self-Updating Object (SUO) architecture. To do so, you may either switch to using the new SUO objects. Or you may add the SUO API to your current objects. For more details, please see the section at the end of this appendix which covers the PFC 6.0 Release.

Empty, Placeholder, "Virtual" User Events

in which you are responsible for filling with the proper script.

Note
Take note throughout this document of any of these events which have this indicator beside them. Again, you are responsible for providing the code for these events for your PFC application to function properly. Of all of the empty user events which exist, these five are very KEY and important, and therefore they are worth calling your attention to them upfront:

pfc_BeginTran Begin your database transaction
pfc_EndTran End your database transaction

Note These two events control your database transactions. Therefore, they are the KEY to the success of your client/server application!

pfc_PreOpen Basically, this is the first script that executes (that you control)

In here you may:

• Turn on any Window Services
• Register the window with the Security Service
• Set your Help ID
• Disable the CloseQuery logic if appropriate

Since this event is triggered at the top of the Open event, you want to limit things done in here until after the Open event completes. That leads us to the next event…

pfc_PostOpen This event is posted from the PFC’s Open event, so it should execute after the window is actually open and is displayed.

In here you may perform longer-running processes such as:

• Of_SetTransObject( )’s (if no tabs involved)
• Database retrievals
• Other long-running processes
• Things that can wait until this event executes
• Things that may need to close the opening window

pfc_Open Open your sheets from your frame here, and
Open another sheet, window or file from another sheet here

Please be sure to read up on these and other empty user events in detail in the following section.

Tell me more about everything in pfc_w_master…

Now that you have an overview of what’s in pfc_w_master, let’s cover each of pfc_w_master’s Instance Variables, Functions and Key Events in detail. We’ll list them all here for your quick reference convenience. And then we’ll take each category one at a time, outlining the particulars of each and every Instance Variable, Function and Key Event.

Key
	è Instance Variable
	è Event with PFC script
	è Event with PFC script that you may want to extend
	è Event Placeholder, intended for you to add script to
	è Function
	è Protected: scope
	è Public: scope
	è PowerScript Native
5.0.02	è New in PFC Release 5.0.02
Note	è Breakpoint - Stop and take note!
Bug Alert!	è Self-explanatory <s>

pfc_w_master

Instance Variables

any ia_HelpTypeID
boolean ib_CloseStatus
boolean ib_DisableCloseQuery
boolean ib_SaveStatus 5.0.02
u_dw idw_Active
n_cst_resize inv_Resize
n_cst_winsrv inv_Base
n_cst_winsrv_preference inv_Preference
powerobject ipo_PendingUpdates[ ]
string is_DBErrorMsg 5.0.02

Shared Variables

< None >

Structures

< None >

Functions

of_GetCloseStatus ( ) returns boolean
of_GetDWType ( datawindow adw_dw ) returns integer
of_GetSaveStatus ( ) returns boolean 5.0.02
of_SetBase ( boolean ab_switch ) returns integer
of_SetDBErrorMsg (string as_msg) returns integer 5.0.02
of_SetPreference ( boolean ab_switch ) returns integer
of_SetResize ( boolean ab_switch ) returns integer
of_UpdateChecks ( ) returns integer

External Functions

< None >

Events

Close ( ) returns long
CloseQuery ( ) returns long Pre-5.0.03
Move ( integer xpos, integer ypos ) returns long
Open ( ) returns long
pfc_AcceptText ( powerobject apo_control [ ], boolean ab_focusonerror ) returns integer Pre-5.0.02
pfc_BeginTran ( ) returns integer
pfc_Close ( )
pfc_ControlGotFocus ( dragobject adrg_control )
pfc_DBError ( ) returns integer5.0.02
pfc_Descendant ( ) returns boolean
pfc_EndTran ( integer ai_update_results ) returns integer
pfc_Help ( ) returns integer
pfc_MessageRouter ( string as_message ) returns integer
pfc_MicroHelp ( string as_microhelp )
pfc_New ( )
pfc_Open ( )
pfc_PageSetup ( ) returns integer
pfc_PostOpen ( )
pfc_PostUpdate ( powerobject apo_control [ ] ) returns integer
pfc_PreClose ( ) returns integer
pfc_PreOpen ( )
pfc_PreUpdate ( ) returns integer
pfc_Print ( ) returns integer
pfc_PrintImmediate ( ) returns integer
pfc_Save ( ) returns integer
pfc_SaveAs ( )
pfc_Update ( powerobject apo_control [ ] ) returns integer
pfc_UpdatesPending ( powerobject apo_control [ ] ) returns integer Pre-5.0.03
pfc_Validation ( powerobject apo_control [ ] ) returns integer
Resize ( ) returns long

pfc_w_frame

Functions

of_SetSheetManager (boolean ab_switch) returns integer
of_SetStatusBar (boolean ab_switch) returns integer

Events

Activate ( ) returns long
Move ( integer xpos, integer ypos ) returns long
pfc_Cascade ( ) returns integer
pfc_Layer ( ) returns integer
pfc_MicroHelp ( string as_microhelp )
pfc_MinimizeAll ( ) returns integer
pfc_Open ( )
pfc_PostOpen ( )
pfc_PreOpen ( )
pfc_PreToolBar ( n_cst_toolbarattrib anv_toolbarattrib )
pfc_TileHorizontal ( ) returns integer
pfc_TileVertical ( ) returns integer
pfc_ToolBars ( ) returns integer
pfc_UndoArrange ( ) returns integer
Resize ( ) returns long

pfc_w_sheet

Events

Activate ( ) returns long
pfc_ControlGotFocus ( dragobject adrg_control )
pfc_MicroHelp ( string as_microhelp )
pfc_PreOpen ( )

pfc_w_response

Events

pfc_Apply ( )
pfc_Cancel ( )
pfc_Default ( )
pfc_PreOpen ( )

Related Objects to read up on

n_cst_AppManager Application Manager

n_cst_DWSrv_Linkage DataWindow Linkage Service
n_cst_WinSrv Basic Window Service
n_cst_WinSrv_Preference Window Preference Service
n_cst_Resize Window Resize Service

n_cst_WinSrv_SheetManager (Frame) Sheet Manager Service
n_cst_WinSrv_StatusBar (Frame) Status Bar Service

pfc_w_master’s Instance Variables

Instance Variables

any ia_HelpTypeID
boolean ib_CloseStatus
boolean ib_DisableCloseQuery
boolean ib_SaveStatus 5.0.02
u_dw idw_Active
n_cst_resize inv_Resize
n_cst_winsrv inv_Base
n_cst_winsrv_preference inv_Preference
powerobject ipo_PendingUpdates[ ]
string is_DBErrorMsg 5.0.02

Shared Variables

< None >

Structures

< None >

Instance Variable ProtectedPublic,Type, Name	What is it?	What is it used for?
any ia_HelpTypeID	Help Type ID for window The ID of the keyword or topic to show for Help for this window	Tells the ShowHelp function which keyword or topic to jump to automatically when the user hits F1 for Help from this window. You need to set it in your window if you would like Help to navigate for that window. Ex: In your pfc_PreOpen event for your particular window: If you are using keywords ia_HelpTypeID = "Part#" If you are using topic numbers ia_HelpTypeID = 143 Otherwise, Help will open using "" <empty string> as the keyword, and the user will be placed on the Index tab ready to enter a keyword.
boolean ib_CloseStatus	Status - Closing? Are we in the middle of the closing process at this time?	PFC sets this to TRUE at the top of theCloseQuery event, and back to FALSE if the close is aborted. Outside of this window, you may check this flag if you need to know if the user is in the process of closing via of_GetCloseStatus( ) returns boolean Ex: In your pfc_Validation event for your DataWindow: ////////////////////////////////////////////////////////////////////////////// // // NOTE: Ancestor is overridden!! // ////////////////////////////////////////////////////////////////////////////// // Override ancestor’s code (so that we may check ancestor’s return code) // Check ancestor’s return code… // Note that with PowerBuilder 6.0 you can do this easier // This is done so that if the PFC’s ancestor already found an error, // we want do not want to continue with our checks // and then possibly return a misleading return code // that says we have passed our validation errors li_rc = Super::EVENT pfc_validation() IF li_rc <> 1 THEN return li_rc // Make sure we have a valid row before we begin our validation checks IF this.GetRow() < 1 THEN return 1 // Bypass validation checks if Closing window lw_parent //If you like to avoid dynamic calls, use w_master here this.of_GetParentWindow(lw_parent) IF isvalid(lw_parent) THEN IF lw_parent.dynamic of_GetCloseStatus ( ) THEN RETURN 1 END IF <dw’s validation checks>
boolean ib_DisableCloseQuery	Disable Close Query? Do we want to skip CloseQuery logic when the user closes window?	If you set this to TRUE, the entire PFCCloseQuery logic will be skipped. Therefore, if the user closes window with a validation error or has not saved their changes, they will not be asked if they wish to do close or save. Instead the window should just close. It is helpful to set this boolean instance variable to TRUE in cases where you know that the window should be read-only, and therefore no updates should be allowed. This is because the PFCCloseQuery might just kick in when it finds some DataWindow that was actually modified behind the scenes and then ask the user if they would like to save. The user will be sitting there thinking, "What’s this? I haven’t even changed anything! In fact, I can’t!". Ex: In your pfc_PreOpen event for your particular window: // To protect the user from being able to save data on "read only" windows, by responding "Yes" to a message that says that the data has changed would you like to save? m_xxx_master lm_menu lm_menu = this.menuid IF lm_menu.m_file.m_save.Enabled THEN ib_DisableCloseQuery =FALSE ELSE ib_DisableCloseQuery =TRUE END IF
boolean ib_SaveStatus 5.0.02	Status - Saving? Is the window in the process of saving data?	PFC sets this to TRUE in the pfc_Save event, temporarily around the pfc_Update event … From PFC’s pfc_Save event: ib_SaveStatus = True li_save_rc = This.Event pfc_Update (ipo_PendingUpdates) ib_SaveStatus = False Whenever ib_SaveStatus is TRUE, no modal windows should be allowed to open, because we are in the middle of a save transaction. If you are outside of the window, you may call of_GetSaveStatus( ) returns boolean to see if the window is in the process of saving. If ib_SaveStatus is TRUE, PFC calls of_SetDBErrorMsg( ) in pfc_u_dw’s dberror to capture and store the error message into is_DBErrorMsg, rather than display them.
u_dw idw_Active	Last Active DataWindow control reference	PFC keeps this reference variable pointing to the Last active DataWindow control for you. Whenever you send a message from your menu, the "Message Router" has a prioritized list of objects to attempt to route the message to… One of the last objects in the Message Router’s list is to check if there is a valid last active DataWindow control reference- IF IsValid(idw_Active). If so, then the pfc_MessageRouter event will attempt to route the message to this last active DataWindow control. Please see the pfc_MessageRouter KEY event for details on this. You may also use this reference variable to refer to the (current and/or last) active DataWindow control. Ex: In pfc_SaveAs event for your particular window: IF IsValid (idw_Active) THEN idw_Active.SaveAs() END IF
n_cst_resize inv_Resize	Window Resize Service instance	If/when you call of_SetResize (TRUE) to turn on the Window Resize Service, this instance of the Window Resize NVO is CREATEd so that you and the PFC may call Window Resize Services. Note: The Resize Service is not only a Window Service. It also services other objects, such as User Objects, Tab Controls, etc. Basically, it services any object that contains a control array of visual objects. Because the Resize Service is really a service to many different objects, not just a window, the Resize NVO is inherited from a native PowerBuilder NonVisualObject directly, rather than being inherited from n_cst_winsrv like the other two Window Services. Note: The Window Resize Service is grouped in the PFCWNSRV.PBL though because it is thought of as a Window Service. This is because the Window begins by re-routing a pfc_resize message to the Window Resize Service instance. In turn, the Window Resize knows which objects are registered with it, so it routes messages to all of them. They also may have their Resize Service turned on, and will therefore resize their controls. This resizing process trickles down nicely. Note: The instance of inv_Resize is automatically destroyed for you in PFC’s Close event via of_SetResize (FALSE). Ex: In pfc_PreOpen event for your particular window - which is opened Original! style: (Note This needs to be before the Open event because that is where the PFC does the preference resizes) this.of_SetResize (TRUE) this. inv_Resize.of_register (dw_1,"ScaletoRight&Bottom") Ex: In pfc_PreOpen event for your particular sheet - which is not opened Original! style: (Note Again, this needs to be before the Open event because that is where the PFC does the preference resizes) Note TheResize event executes even before theOpen script executes if you do not open your sheets in the Original! Style. In that case, you will have to make some special provisions for telling the Window Resize Service what the actual, true size of the window was before it was resized due to Layering and such. The following is one approach, there are others as well. this.of_SetResize(TRUE) // To obtain the accurate size, you must open window in it's ORIGINAL size //Messagebox("Window Size","Width: " +& // string(this.workspacewidth())+"~r~nHeight: "+& // string(this.workspaceheight())) // (It is not necessarily the same as the Window’s Position Tab Width & Height) this.inv_resize.of_SetOrigSize(2478,1273) //Then Plug in the width & height //here according to what the MessageBox said //Then continue with registering objects this.inv_resize.of_Register(dw_customer,"scaletoright&bottom")
n_cst_winsrv inv_Base	Basic Window Service instance	If/when you call of_SetBase (TRUE) to turn on the Basic Window Service, this instance of the Basic Window NVO is CREATEd so that you may call Basic Window Services. But because all window services are descendants of n_cst_winsrv (and have n_cst_winsrv functions available to them), use this object only when you require basic window services only. This basically boils down to only when you need to center a window that is not already using the Preference service. Note: The instance of inv_Base is automatically destroyed for you in PFC’s Close event via of_SetBase (FALSE) Ex: In pfc_PreOpen event for your w_response perhaps: this.of_SetBase(TRUE) this. inv_Base.of_Center()
n_cst_winsrv_preference inv_Preference	Window Preference Service instance	If/when you call of_SetPreference (TRUE) to turn on the Window Preference Service, this instance of the Window Preference NVO is CREATEd so that you and the PFC may call Window Preference Services. The Window Preference Service is a big hit with the users. It is very helpful. There are however a few things to be aware about it… Note The way that the Preference Service comes out of the box, it saves every single menu item toolbar position. This drastically slows down the opening of your windows. And to top it off, the user doesn’t even have an option to customize these, so trying to store their preferences doesn’t even make sense. In addition, this can really throw you for a loop when you change your menu’s toolbar buttons, and when you run your application, it is working off of old menu item toolbar positions. Forewarned is forearmed! … Therefore, you may wish to modify it to not save the positions of all of the toolbar buttons. Note The Preference Service does not store the Maximized! Style for the frame. You may wish to customize yours to do so. Note The Preference Service does not apply to certain "application" attributes, such as the ToolBarText. There is a new service to handle those application preferences in the PFC 6.0 Release.. Note: The instance of inv_Preference is automatically destroyed for you in PFC’s Close event via of_SetPreference (FALSE). Ex: In pfc_PreOpen event for your w_sheet perhaps: (Note This needs to be before the Open event because that is where the PFC does the preference restores) this.of_SetPreference (TRUE) this. inv_Preference.of_SetToolBars (TRUE) this. inv_Preference.of_SetWindow (TRUE)
powerobject ipo_PendingUpdates[ ]	Array of DataWindow controls (and other objects) with Updates Pending	PFC populates this array with all of the DataWindow controls which have updates pending in the pfc_UpdatesPending event from of_UpdateChecks() during theCloseQuery or pfc_Save process. If you have extra objects which have updates pending, you would extend the pfc_UpdatesPending event and add those controls to this array. This array is then passed to the pfc_Validation, pfc_Update and pfc_PostUpdate events to validate, update and perform post-updates on each control in the array.
string is_DBErrorMsg 5.0.02	DBError (event) message Stored error message from a database update (from a DataWindow’s DBError event) …which is waiting to be displayed until after the entire transaction has ended (rolled back)	If an database error occurs during the pfc_Update event, the error message (from a DBError event for a DataWindow) is held here for display after the pfc_EndTran event properly ends the transaction (after appropriate ROLLBACK). Note Why? Because it is very important during a transaction to not display any messageboxes or other modal type windows! This prevents locks from being held on the database while updates have not yet been COMMITed or ROLLBACKed. PFC calls of_SetDBErrorMsg (string as_msg) returns integer in pfc_u_dw’s dberror to capture and store the error message into is_DBErrorMsg, rather then display them if ib_SaveStatus is TRUE. You should too if you are doing any special update processing within pfc_Update. If there is an error during the pfc_Update and Len(is_DBErrorMsg)>0, the PFC pfc_Save event will trigger the pfc_DBError event which will then display this saved message in is_DBErrorMsg. After displaying it, it is reset to an empty string via of_SetDBErrorMsg("")

pfc_w_master’s Functions

Functions

of_GetCloseStatus ( ) returns boolean
of_GetDWType ( datawindow adw_dw ) returns integer
of_GetSaveStatus ( ) returns boolean 5.0.02
of_SetBase ( boolean ab_switch ) returns integer
of_SetDBErrorMsg (string as_msg) returns integer 5.0.02
of_SetPreference ( boolean ab_switch ) returns integer
of_SetResize ( boolean ab_switch ) returns integer
of_UpdateChecks ( ) returns integer

External Functions

< None >

Function ProtectedPublic, Name (arguments), return type	What is it? Arguments Return Values	What does it do? When should I call it?
of_GetCloseStatus ( ) returns boolean	Status - Closing? Are we in the middle of the closing process at this time? Returns boolean: TRUE = Window is closing FALSE = Window is not closing	Reports whether or not the window is in the process of closing. This function simply returns the value of the (protected) boolean ib_CloseStatus instance variable. Since ib_CloseStatus is protected, this allows other objects to query it. Note: Call this function to determine whether a window is closing. Things such as validation errors in the PFC are usually bypassed if the window is closing. Ex: In your pfc_Validation event for your DataWindow: <check ancestor’s rc> // Bypass validation checks if Closing window lw_parent //If you like to avoid dynamic calls, use w_master this.of_GetParentWindow(lw_parent) IF isvalid(lw_parent) THEN IF lw_parent.dynamic of_GetCloseStatus ( ) THEN RETURN 1 END IF <dw’s validation checks>
of_GetDWType ( datawindow adw_dw ) returns integer	What kind of DataWindow is this?… Desc of u_dw? + Linked? Returns integer: -1 = Error 0 = DW not a descendant of u_dw 1 = DW is a descendant of u_dw and it is not linked 2 = DW is a descendant of u_dw and it is linked	Indicates whether a DataWindow is a descendant of u_dw and whether or not it uses the linkage service Note: Internal Use Only (so you would rarely call it) Ex: In the PFC’s pfc_UpdatesPending event: li_dwtype = of_GetDWType(ldw_dw) If li_dwtype < 0 Then Return -1
5.0.02 of_GetSaveStatus ( ) returns boolean	Status - Saving? Is the window in the process of saving data? Returns boolean: TRUE = Window is in the save process FALSE = Window is not in the save process	Reports whether or not the window is in the process of saving, specifically whether you are in the pfc_Update event. This is because at that point you are in the middle of a transaction, and you do not want any modal windows to open which would hold up the transaction in progress. This function simply returns the value of the (protected) boolean ib_SaveStatus instance variable. Since ib_SaveStatus is protected, this allows other objects to query it. Note: Call this function to determine whether a window is in the process of saving. If it is, then call of_SetDBErrorMsg( ) to store the error message until after the transaction has ended. Ex: In the PFC’s DBError event for the DataWindow, here is what the PFC does: ls_message = & "A database error has occurred.~r~n~r~n~r~n" + & "Database error code: " + String (sqldbcode) + "~r~n"+& "Database error message:~r~n" + sqlerrtext // Determine if the window is in the PFC save process. This.of_GetParentWindow(lw_parent) If IsValid(lw_parent) Then If lw_parent.TriggerEvent ("pfc_descendant") = 1 Then lb_pfcsaveprocess = lw_parent.of_GetSaveStatus() End If End If If lb_pfcsaveprocess Then // Suppress the error until after a rollback // Store the message on the parent window for later use. lw_parent.of_SetDBErrorMsg(ls_message) Else … End If
of_SetBase ( boolean ab_switch ) returns integer	Turn on/off Basic Window Services Argument boolean ab_switch: TRUE = Enable service FALSE = Disable service Returns integer: 1 = Success -1 = Error	Enables or disables n_cst_winsrv, which provides Basic Window Services. This function simply creates or destroys an instance of n_cst_winsrv. If/when you call of_SetBase (TRUE) to turn on the Basic Window Service, an instance of n_cst_winsrv inv_Base is created on pfc_w_master so that you may call Basic Window Services. Note: The instance of inv_Base is automatically destroyed for you in PFC’s Close event via of_SetBase (FALSE) Note: Use this function to turn on the Basic Window Services… Note …but only if you need to… Because all window services are descendants of n_cst_winsrv (and have n_cst_winsrv functions available to them), use this object only when you require basic window services only. This basically boils down to only when you need to center a window that is not already using the Preference service. Ex: In pfc_PreOpen event (so that it is moved before it is displayed) for your w_response perhaps: this.of_SetBase(TRUE) this. inv_Base.of_Center()
5.0.02 of_SetDBErrorMsg (string as_msg) returns integer	Store the DBError Message to be displayed after transaction has ended Argument string as_msg : Text of the DB Error message, for example a string containing information such as sqldbcode and sqlerrtext from u_dw’s DBError event Returns integer: 1 = Success -1 = Error	Stores any DBError message that may have occurred during the process of saving, specifically when it was in the pfc_Update event. The message is stored rather than displayed in a modal window because at that point you are in the middle of a transaction, and you do not want any modal windows to open which would hold up the transaction in progress. This function simply stores the DBError message in the (protected) boolean is_DBErrorMsg instance variable. Since is_DBErrorMsg is protected, this allows other objects to query or change it. Note: Call this function to store a DBError message when a window is in the process of saving. Ex: In the PFC’s DBError event for the DataWindow, here is what the PFC does: ls_message = & "A database error has occurred.~r~n~r~n~r~n" + & "Database error code: " + String (sqldbcode) + "~r~n"+& "Database error message:~r~n" + sqlerrtext // Determine if the window is in the PFC save process. This.of_GetParentWindow(lw_parent) If IsValid(lw_parent) Then If lw_parent.TriggerEvent ("pfc_descendant") = 1 Then lb_pfcsaveprocess = lw_parent.of_GetSaveStatus() End If End If If lb_pfcsaveprocess Then // Suppress the error until after a rollback // Store the message on the parent window for later use. lw_parent.of_SetDBErrorMsg(ls_message) Else … End If
of_SetPreference ( boolean ab_switch ) returns integer	Turn on/off Window Preference Service Argument boolean ab_switch: TRUE = Enable service FALSE = Disable service Returns integer: 1 = Success -1 = Error	Enables or disables n_cst_winsrv_preference, which provides Window Preference Services. This function simply creates or destroys an instance of n_cst_winsrv_preference. If/when you call of_SetPreference (TRUE) to turn on the Window Preference Service, an instance of n_cst_winsrv_preference inv_Preference is created on pfc_w_master so that you and the PFC may call Window Preference Services. Note: The instance of inv_Preference is automatically destroyed for you in PFC’s Close event via of_SetPreference (FALSE) Note: Use this function to turn on the Window Preference Service. Ex: In pfc_PreOpen event for your w_sheet perhaps: (Note This needs to be before the Open event because that is where the PFC does the preference restores) this.of_SetPreference (TRUE) this. inv_Preference.of_SetToolBars (TRUE) this. Inv_Preference.of_SetWindow (TRUE)
of_SetResize ( boolean ab_switch ) returns integer	Turn on/off Window Resize Services Argument boolean ab_switch: TRUE = Enable service FALSE = Disable service Returns integer: 1 = Success -1 = Error	Enables or disables n_cst_resize, which provides Window Resize services. This function simply creates or destroys an instance of n_cst_resize. If/when you call of_SetResize (TRUE) to turn on the window resize service, an instance of n_cst_resize inv_Resize is created on pfc_w_master so that you and the PFC may call Window Resize Services. Note: The instance of inv_Resize is automatically destroyed for you in PFC’s Close event via of_SetResize (FALSE) Note TheResize event executes even before theOpen script executes if you do not open your sheets in the Original! Style. In that case, you will have to make some special provisions for telling the Window Resize Service what the actual, true size of the window was before it was resized due to Layering and such. There are a few approaches to deal with this… Please refer to n_cst_resize inv_Resize for notes and examples on this as well as on the Resize Service in general. Note: Use this function to turn on the Window Resize Service. Ex: In pfc_PreOpen event for your particular window: (Note This needs to be before the Open event because that is where the PFC does the preference resizes) this.of_SetResize (TRUE) this. inv_Resize.of_register (dw_1,"ScaletoRight&Bottom")
of_UpdateChecks ( ) returns integer	Check for any validation errors or if there are any unsaved changes pending Returns integer: 1 = Updates are pending and there are no validation errors 0 = No updates pending -1 = AcceptText Error -2 = UpdatesPending Error -3 = Validation error	Triggers the following events pfc_AcceptText to do an AcceptText on all DataWindows. If no AcceptText errors… pfc_UpdatesPending to look for any DataWi