PowerBuilder Authors: Chris Pollach, Yeshim Deniz, Jayaram Krishnaswamy, Kevin Benedict, Avi Rosenthal

Related Topics: PowerBuilder

PowerBuilder: Article

PocketBuilder Application Help

Building and integrating

Summertime here in Canada's "Great White North" is hot and humid but I definitely didn't miss the Florida weather or the hurricane season at TechWave. Instead, I was building my first application Help feature for a Pocket PowerBuilder application.

I thought this would be quite straightforward since I've done this many times before for a standard PowerBuilder application. I immediately hit F1 on my laptop and checked out the ShowHelp( ) command of PPB. Guess what... "Not supported." Okay, so maybe I should have gone to TechWave! But 38ºC (100.4ºF), floating here in the pool is not bad either.

After doing a little more research on the PPC O/S I discovered that it's very HTML based in many of its ancillary operations. I also poked around the various PPC built-in applications and found that those applications that supported some type of Help seemed to display HTML (Web) based Help. So this was the avenue I decided to embark on since the PPC has the Internet Explorer application built in. Breaking the main problem down, there seemed to be three subproblem areas:

  1. Building efficient HTML Help (remember - the PPC device does not have a lot of storage)
  2. Invoking the HTML Help once you have it available to the PPB application
  3. Resolving any differences between the PPC and native mode application invocation
Turning to the first problem, building HTML Help, I decided to explore the "Doc2Help" product that I've been using for over 10 years to produce Help for Java, VB, PB, "C", Delphi, etc., built applications.

"Doc2Help" was originally built by WexTech Systems of New York, but in recent years was sold to ComponentOne (a well-known software development firm specializing in VB and .NET add-ons). ComponentOne is a merger of APEX Software Corporation and VideoSoft. You can read all about their various products at www.componentone.com. As you can tell by the product title, this Help tool stands for "Document to Help" - in particular an MS Word document. The Help author merely creates an MS Word document and uses appropriate styles, headings, and tags to declare what the Help document should look like.

One interesting thing about the Doc2Help product is that it forces writers to adhere to a good technical layout and provides them with various standard layouts during the start of the Help project. Once completed, the document can be printed or converted to an Adobe PDF for viewing. The other real bonus is that the finished document can also be used to build MS Help, Java, Compiled HTML, or HTML 4.0 Help files.

To test a pilot PPB application with HTML Help, I chose to use my STD Foundation Class-built "Order Entry" application (you can find that on Sybase's CodeXchange server). I'm also using the latest version of "Doc2Help," which is release 7.2 (standard edition). For the rest of this article I'll lead you through the steps I needed to do in order to generate, integrate, and test this application to evolve its Help facility. For those who would like to see the immediate end result, please feel free to download the latest version of the "Order Entry" application from CodeXchange with the Help file integration already coded. You can access this at http://pocketpb.codexchange.sybase.com/Servlets/ProjectDocumentList?folderID=422. Just make sure you download the example application version 1.5.2 - version 2 (959.37K from the OES2004_ 08_31.zip file). This download includes the application and the final HTML-generated Help files.

Starting Your Help
To start a "Doc2Help" (D2H) project, first start the main D2H console. This interface will guide you through the whole process. In the main console you'll need to select "Create New Project" (see Figure 1). Selecting this will invoke a D2H wizard that will guide you through some of the important starting information such as: what type of Help file are you generating, the name of your project and Help file, the Help file(s) location, etc. The wizard will take your information, allocate the appropriate subfolders and control files, and then invoke the MS Word word processor. The first part of the wizard is important in defining your look and feel and to target your writing style. For this I normally choose "Normal Template." If you look at the "New Project Wizard," you can see the layout manager preview showing the technical writer how the document will be formatted. At this point, you have six layouts to choose from.

The next part of the wizard will ask you for the type of Help. For the PPC I'll choose HTML 4.0, which is generally accepted as the cross-platform standard format used by most Web developers today - especially when trying to support section 508 (CLF in Canada).

With these two important pieces of information completed, continue through the wizard to define the Help project file and then press finish. At this time, the D2H wizard will complete the folder setup and launch the MS Word word processor. One of the new noticeable items you'll see in the word processor is a D2H toolbar that is added automatically to your MS Word environment (see Figure 2). This toolbar will allow you to select and include special Help features into your document that will be sent to the appropriate Help compiler (depending on the type of Help output you desire).

Help Document
In the D2H-generated MS Word document you can now type in the relevant information for your Help. First I replaced the generated "Chapter 1" heading with "Order Entry Application" (see Figure 3) and then I added all the relevant section headings like Overview, Common Features, Starting the Application, and Activities. Of course, for your Help, you can declare these subheadings however you like. In D2H, to mark a subheading of the main Help document, use the "style" dropdown located in the upper left part of the MS Word formatting toolbar. Select values such as "Heading 1," "Heading 2," etc. Once done, the D2H macros will take over and reposition, align, and style the selected text. This process continues for other sub-subheadings and the main text, which is marked as Body Text. You may also insert all links to information in the left margin and links to other topics, index entries, glossary items, etc. All of this information will be converted to HTML at the touch of a button!

To build the Help file, you only have to use the "Make Target" icon on the D2H toolbar. Pressing this button will direct D2H to interact with the appropriate compiler(s) and manage the project file settings appropriately. This can be done from the main D2H controller dialog or the same icon is visible from the D2H toolbar inside of MS Word. To view the finished product, you just need to select the "View Target" icon on the controller or D2H MS Word toolbar as well. That's all there is to it for the basics.

The only thing to do at the end to complete (polish) your Help project is fine-tune the HTML. When you first build the HTML Help file(s), you'll see that it's more for the robust MS Windows PC world and the Internet Explorer application - utilizing such features as Frame Sets, Cascading Style Sheets, JavaScript, etc. Also, the file size is quite robust because of the default features used by D2H.

All D2H knows for the moment is to use HTML 4.0, which is cross-platform as much as possible. Although this would work on the PPC, it's overkill for this platform. To correct the situation though is very easy - just open the D2H controller window for your Help project and select the Help target (in this case the type is HTML 4.0) and edit a few properties such as GenerateCSS (off), DynamicTOC (off), and FrameSet (off) (see Figure 4). This will generate a much smaller set of HTML files, which will be just fine for PPC viewing.

On the Order Entry application's Help file, the first generation consisted of 10 files for a total size of 53K bytes. Upon changing the project target's properties as I suggested above, the generation resulted in eight files and 43K bytes - a savings of two files and 10K bytes. I copied each set of Help files to the PPC (I use a Dell Axim X30 with the PPC2003SE O/S for testing) as well as IExplorer version 6.0.2800.1106 under Windows 2000 for a native look and feel. After making the changes from above, the Help file, when viewed in W2000 IE, was not as rich but still readable. All the jumps worked well. On the PPC, the first Help file build was very cumbersome to read, as the PPC IE does not support Frame Sets. However, the second build looked just as good on the PPC as it did under native windows. That was very comforting to me.

Native MS Windows
Pocket PowerBuilder's development environment will run under either MS Windows 2000 or XP. You may also test your PPC application through an emulator running on that environment or natively using the "Run" icon on the PPB toolbar. Either way, the PPB application is running using the Win32 instruction set. This means that your code has to differentiate between the native and PPC execution. To do this you can use a few helpful pieces of information that can be acquired from the GetEnvironment method call. This populates an environment structure that contains a field named OSType. This field will have the value WindowsNT! if you're running under the native MS Windows or emulator.

More Stories By Chris Pollach

Chris Pollach is a Senior Consultant with over 30 years experience in Systems and Software Analysis, Development, Maintenance and Technical Support, mainly in the areas of GUI Design, MS-Windows Programming, Java / .NET Programming, Wireless, Application / Web Server Design & Programming, Object Oriented Development Tools and Methodologies, Data Base, Data Communications and Network application development. He has participated in numerous technical, planning and management roles, as well as consulted and educated in these fields for a diverse clientele. He is also the owner of “Software Tool & Die Inc.” a company dedicated to provide custom software and education solutions on Object Oriented business systems.

As an educator, Chris is certified to teach PowerBuilder (first in Canada), MS-SQLServer, Sybase’s Enterprise Application Studio and EAServer integrated application/web development environment. He is former Certified SilverStream developer (CSSD) and current Certified PowerBuilder Developer – Associate / Professional (CPD-P) as well as a Certified Sybase Tools Instructor (CSI).

Chris has written numerous articles in various popular personal computer magazines, newsletters and is the author of the PowerGuide and PowerExpert products as well as the STD Foundation Classes. Currently, Chris has developed a Foundation Class library for Sybase's PocketBuilder, SAP's PowerBulder and EAServer products and now Appeon Web & mobile products that integrates JSP or ASP web development, Section 508 / CLF web standards and mobile applications. A new Web Service framework has also been released for IIs to support PowerBuilder based web service NVUO's!

Chris recently became a 2nd Degree Black in the TaeKwonDo martial art and has developed a Martial Art multimedia study guide using the Component-One “Doc2Help” and Sybase PowerBuilder products. Since the fall of 2004 he became a TaeKwonDo instructor for the City of Ottawa’s Goulbourn program. He has also been certified with the World TaeKwonDo Federation (February 2005 - 1st Dan and October 2008 - 2nd Dan).

Chris was awarded the Sybase “Innovation and Achievement” award for 2005 as voted for by the International Sybase User Group (ISUG). This award was presented for innovations to the PocketBuilder mobile development product, contributions to the PowerBuilder News groups and support of the Ottawa Sybase User Group.

To round his management and leadership skills, Chris is the former president of the Kiwanis Club of Goulbourn and still volunteers his time with the service clubs in his area. He is also the coordinator of the Ottawa Sybase User group and a certified NAUI scuba instructor. For the last three years, Chris has been voted onto the ISUG Board of Directors and holds the position of "Director - North American User Groups".

Comments (0)

Share your thoughts on this story.

Add your comment
You must be signed in to add a comment. Sign-in | Register

In accordance with our Comment Policy, we encourage comments that are on topic, relevant and to-the-point. We will remove comments that include profanity, personal attacks, racial slurs, threats of violence, or other inappropriate material that violates our Terms and Conditions, and will block users who make repeated violations. We ask all readers to expect diversity of opinion and to treat one another with dignity and respect.