pfc_w_master6.0

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

Appendices by Sharon Weinstrom Buntz, Jason Cohen, Glenn G. D’mello, Ken Howe, Greg Schultz and Brian Suter; List: $37.95, Published by Manning, ISBN # 1-88-477755-4

...The following are the ending sections of Appendix J - pfc_w_master,
written by Sharon Weinstrom Buntz

And what about the changes to pfc_w_master in the PFC 6.0 Release ?

As we mentioned earlier, the changes in thePFC 6.0 Release for pfc_w_master are drastic enough (and not finalized as of this writing) to merit leaving them out of the detailed discussions of every instance variable, event and function. Trying to weave the new ones in and talk about all of the changes would be too confusing anyway.

So, as hard as it is now to say with any certainty or any clear knowledge of 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.

The information contained below is current as of PFC 6.0 Beta 4 - Sept, 1997 to the best of my knowledge. To try to make this as useful and accurate as possible, I have obtained some help from the PFC Development Team themselves. However, they are very busy working on it even as I try to write about it!

So now, let’s take a quick look at what’s projected for the future 6.0 release of the PFC for pfc_w_master.

In thePFC 6.0 Release, the Save Process in pfc_w_master will be dramatically enhanced…

First of all, don’t worry, everything was coded with the idea in mind to maintain upwards compatibility! Your previous code should work without any changes. But to take advantage of the new functionality, you would call some new functions, such as

of_SetUpdateObjects ( powerobject apo_objects[ ] ) returns integer

to specify on which objects and in what order the pfc_Save event will perform the updates, versus just defaulting to using the control array

-or-

pfc_SaveObjects ( powerobject apo_objects[ ] ) returns integer

to specify the objects and the order, and to also trigger pfc_Save; used for special, extra or separate save processes to augment the main one

As you can see, the new of_SetUpdateObjects( powerobject apo_objects[ ] ) function and pfc_SaveObjects ( powerobject apo_objects[ ] ) event will provide you with a finer-grained control of the save process. They also provide you with a means to fine-tune your performance, since you would tell the save process exactly which controls to update, rather than having it search through all controls on the window - sometimes even drilling thru layers for user objects, tabs and such. With these new methods, now you can control what gets updated and when. This is because each of these methods allow you to pass an array of PowerObjects. The controls that you load into this array are the controls which you would like to be updated. In addition, the order that you place them into this array, determines which order they will be updated.

The new of_SetUpdateObjects( ) function lets you specify which controls will be included in the normal pfc_Save process. This overrides the normal sequence and selection of what is in the window’s control array. By the way, a new feature of thePowerBuilder 6.0 Release is that all dynamically created controls are now automatically added to the window’s control array. No more messing around with the control array behind the scenes is needed.

So you would call the of_SetUpdateObjects( ) function when you need to change the content and/or the order of the controls that will be updated by the normal pfc_Save process. This content and order is then "remembered" so that whenever the normal pfc_Save process is triggered - pfc_Save knows what to update and in what order to update.

The new pfc_SaveObjects event lets you specify which controls will be included in a special save process, usually in lieu of the normal pfc_Save process. This not only overrides the normal sequence and selection of what is in the window’s control array, but it also fires off the save process as well.

So you would trigger the new pfc_SaveObjects event to fire off a special save process that will specifically update only those controls which you pass to it, in the order that you pass them.

A major enhancement with PFC 6.0 is the introduction of the "Logical Unit of Work" (LUW) Service. This new LUW service makes it easier to process updates from multiple objects all in one or multiple transaction (connection) objects. It is also what drives the window updates. The window save process is now being rerouted to the new non-visual custom user object, the "Logical Unit of Work" (LUW) NVO, named n_cst_luw. With the introduction of the new LUW service, the LUW transaction is no longer tied to the window. This will make it easier to process updates from multiple windows/objects all in one transaction.

The new PFC updateable objects will now be "Self-Updating Objects" (SUO). So this means that the LUW service will tell all of the objects to validate and update themselves, rather than having the service perform these things on the object directly. The benefits of this are encapsulation, polymorphism and future objects being able to be automatically picked up if they know how to perform the SUO functions. So now each object will now have their own functions such as

of_AcceptText( )
of_UpdatesPending( )
of_Validation( )
of_UpdatePrep( )
of_Update( )
of_PostUpdate( )

So each object is responsible for how to accomplish these tasks, for themselves, as well as any of their "components". Having these set of functions, an object now implements the coined phrase "Self-Updating Object Application Programming Interface (SUO API)". The following PFC objects now include these "self-updating objects" functions:

DataWindow
DataStore
ListView *
TreeView *
Tab
UserObject
Window

* Note: These 6.0 ListView and TreeView objects are new, separate PFC LV & TV objects which have the SUO API. This is for upwards compatibility issues. If you use these new objects, you no longer have to override events to have your ListViews and TreeViews update! Another option is to add the SUO API to your existing ListView and TreeView PFE layer objects (see next bullet), and change your pfc_w_master's pfc_save-related scripts.)

And, furthermore, you can create a SUO object yourself. And it will "plug in" effortlessly; the beauty of OO design! … To do so, you would add the SUO API functions to an object of your choice. By doing so, your new SUO object will then automatically be picked up as a "self-updating object" in the window's control array to be included in the save process.

For example, if you were to create a Self-Updating Multi-Line Edit control (MLE) by adding the SUO API functions to it; And then you were to place that control on your window; Then, using the default processing, PFC will pick it up and include in the normal pfc_save process.

All this talk about SUO’s may have made you think that if it is not an SUO, it may no longer get picked up in the save process… But, no, au contraire, PFC 6.0 continues to support non-PFC, plain ol’ native DataWindows and DataStores. In other words, they will also be picked up in the save process even if they are not SUOs, inherited from PFC objects or not.

And, lastly, there is a new pfc_UpdatePrep event. This new event comes before the pfc_PreUpdate in the save process, and it will tell all of the update objects to run their of_UpdatePrep( ).

I suppose this may be because
there is no SUO API of_PreUpdate( ) equivalent of the window’s pfc_PreUpdate
as there is an SUO API of_PostUpdate( ) equivalent of the window’s pfc_PostUpdate
instead, it uses SUO API of_UpdatePrep( ) equivalent of the window’s pfc_UpdatePrep
which comes before the window’s pfc_PreUpdate

Next, in thePFC 6.0 Release, there will be a new "Most Recently Used (MRU) Window" Service.

The most common use for this new MRU service will be to append the last five windows (or entities, such as customers) which were most recently used to the bottom of the File menu list. This allows users to easily go back to windows (or entities) that have previously been opened in earlier sessions.

Another handy use for this new MRU service will be to save the user’s "bookmarks" (or "favorites" as NT4.0 calls them)! Surely, this can prove extremely useful. Especially, if it could be combined with an option for the user to automatically go to their favorite place on startup or something.

Although the MRU service instance is housed in the Application Manager, the pfc_w_master has some new events in order to do things such as:

Populate the MRU attribute object with the text for the key

(so that the MRU service knows how to store the key)
For example, you may wish to include the window name and any special parameters to pass for retrieval arguments

Save the current window’s key to be included in the MRU list

(to be done near the opening and/or near the closing of the window)

Open the particular window properly when the user selects the MRU menu item

As mentioned above, the MRU Service can be used to remember the last set of windows or entities which were used by the current user. By entities, we mean that you can use business items, like Customer IDs, not just windows. To make this clearer, in the PowerBuilder development environment paradigm, windows are appended to the bottom of the File menu. Whereas in Microsoft Word, document names are appended to the bottom of the File menu. So, depending on how you code it, you can remember either the last type of window opened, or you could remember the last customers edited within a window.

The MRU Service is not limited to only the File menu on the window. You may also choose to create some pfcmruX menu items on a different menu item. If you do, then the MRU’s restore is smart enough to place the last items used whereever it finds the pfcmruX menu items.

And although the default is to keep the last five MRU windows, it is not limited to only five. You can add as many pfcmruX items as you desire, and the service will restore them all. If you choose to add a different number of menu items (rather than the default of five), you will need to reset the MRU item count via the service’s of_SetMRUItemCount( ) function.

Also, in thePFC 6.0 Release, the use of Constants makes our code more readable, especially when used to interpret return codes or to pass our arguments…

Here’s the new pfc_w_master public constant which is RETURNed from several events where no action was needed (because for example there were no objects to take action upon)…

Public:
Constant Integer NO_ACTION = 0

And note the convenience and readability of these two new constants in the CloseQuery event, to RETURN in order to either allow the window to close, or prevent the window from closing…

Constant Integer CONTINUE_ACTION = 0
Constant Integer PREVENT_ACTION = 1

Some other things worth mentioning in thePFC 6.0 Release are some exciting new visual user objects that can be placed on any pfc_w_master window…

u_st_SplitBar SplitBar

Now your application can have the "Explorer" look and feel, or
you can allow the user to easily maximize their window real estate.
You can use multiple splitbars on your window, and they work
in conjunction with the resize service

u_ProgressBar Progress Bar

Handier than its ActiveX counterparts

u_Calculator Calculator

Best suited for its DataWindow column uses,
but it can be placed on a window as well

u_Calendar Calendar

Best suited for its DataWindow column uses,
but it can be placed on a window as well,
possibly to select a processing period or something

Furthermore, in thePFC 6.0 Release take note of a few enhancements to a couple of the pfc_w_master Window-related services…

n_cst_Resize Window Resize Service

New way to specify percentages of how to resize/move an object,
so you can have more control over how objects are resized & moved…
For example, if there is a main control that is more important,
that control can stretch faster than the others.

For example, before, there was no way to have two objects, side by side, stretch proportionally as the window stretches. You had to stretch one and move the other, but you couldn't stretch them both... With this enhancement, now you will be able to do this. Plus, you can say which one should stretch faster.

Sorry, the following enhancement to the existing n_cst_WinSrv_SheetManager is no longer targeted as of this writing for the PFC 6.0 Release; it was dropped. Perhaps it will be included in a later release or perhaps it was abandoned for some other reason. I don’t know.
n_cst_WinSrv_SheetManager Window Sheet Manager Service

Option to limit the total number of sheets which can be opened
Option to limit the number of sheets specified by class, title,etc

And, lastly, in thePFC 6.0 Release, there is a new of_MessageBox( ) function in pfc_w_master. This function simply displays a PowerScript MessageBox. However its advantage is that you may manipulate the MessageBox prior to its actual display in any way that you need, to support multi-languages, append extra info, skip it or log it, etc. It takes all of the MessageBox arguments, plus an extra argument for the ID of the message…

of_MessageBox ( string as_id, string as_title, string as_text, icon ae_icon, button ae_button, integer ai_default) returns integer

Please note that this new function is encapsulated into other appropriate objects as well, such as the new pfc_n_base (ancestor of all non-visual user objects). Think of it along the same lines as the of_GetParentWindow( ) functions, which can be done on any of 23 different controls, such as a DataWindow, a Tab, a TabPage, a DataWindow on a TabPage within a Tab, a CommandButton - whatever, and it still comes back with the window that it sits upon.

Also, please note that this of_MessageBox( ) function is different from, and should not be confused with, the Error Service’s gnv_app.inv_error.of_Message( ) function.

Appendix Summary

Hopefully, this has given you a thorough understanding of the Great, Great GrandDaddy of all PFC windows, pfc_w_master.

We have covered the 5.0.0# hierarchy and the functionality of your windows in detail. And we have given you a heads up on what is projected for thePFC 6.0 Release as well. We hope you have found this information useful, and we hope that you can easily flip back here as a quick reference in the future.

If you have any questions or feedback on any of this, please feel free to drop me a line at sbuntz@texas.net . I will look forward to hearing from you. In honor of my commitment to quality and my efforts to not spread any misinformation, I will keep any corrections and/or clarifications available online at http://www.pfccheatsheet.com/ . (And if it ends up being elsewhere, there will at least be a pointer to it from there.) Because we live in an age now where things are rapidly changing. And even so, there is no longer one person, or even a small group of people, who really understand and know everything there is now to know.

About the Author

Sharon Weinstrom Buntz is a CPD Professional who works for NewData Strategies (NDS), a company which provides "high-technology" software, consulting and education services. Sharon is currently a PFC/PowerBuilder mentor at Education Service Center (ESC), Region 20 in San Antonio, Texas.

Her "Cheat Sheet" for PFC/PowerBuilder "Help" is available for your assistance and convenience at:
http://www.pfccheatsheet.com/

Another PFC resource to keep bookmarked is Boris Gasin’s (of Advent 2000, Inc.) PFC Guide at:
http://www.pfcguide.com/

And don't forget Rik Brooks' Dojo at:
http://www.pics.com/byte/dojo.htm

Please feel free to send Sharon an email at sbuntz@texas.net .

Sharon is forever grateful to the PFC Development Team and the other PFC experts that helped her create, compile and edit this appendix, especially Claudio Quant, Mark Overbey, Brian Grimm, Boris Gasin, Andrew "Brez" Bereznak, Steve Benfield, John Olson, Jon Credit, Bob Fields, Gregory R. George, Ken Howe, Jill Moritz, Judy Cote and Michael Campbell.

And, of course, Sharon would like to thank Rik Brooks for giving her this wonderful opportunity to be a part of this helpful PFC book. Rik is a true pleasure to work with and learn from.

Her heart also goes out to the wonderful people at ESC and NDS who have worked with Sharon, together learning all about the PFC… Linda Sweet, David Terry, Emilio Flores, Mike Uhl, John McCauley, Dan Perez, Al Holden, Ching-Shen Chen, Ching-Shyong Li, Crystal Fox, Jesse Morales, Laura Ellison, Michael Stehling, Robert Okruhlik, Robert Pruski, Roland Gonzales, Thomas Evans, Robbie Hollis, Brenda Hutzler, Gwen Bolden, Joyce McDonald, Lesa Garcia, Paul Rector, Beth Rehn and, again, her wonderful and talented mentor Judy Cote.

Next, Sharon has not forgotten all of her PFC friends on the pfcsig mail list, the pfc-users mail list and the Powersoft newsgroups. The people there so graciously share all of their PFC wisdom and knowledge with other PFCers. And it is a most beautiful experience to be a part of that team spirit that makes anything possible. Hats off to all of them!

And, last but not least… switching now to first person <g>… I would like to personally thank all of my family, my puppies and my husband, John, for all of their love, patience and support... especially while I was submerged <s>.

Visit our sponsors

Home

Know where to go

Work smarter, not harder

Answers at your fingertips

Home | Top