Tech Articles

Chapter 5 of PowerBuilder 9: Advanced Client/Server Development included a discussion on how to add items to the New dialog within the PowerBuilder IDE. This article will review that information and look at a couple of additional techniques for extending the PowerBuilder IDE

Adding Items to the New Dialog
All versions of PowerBuilder 7 and beyond allow you to add items to the New Dialog by adding entries to the registry. First navigate to:

HKEY_LOCAL_MACHINE\SOFTWARE\Sybase\PowerBuilder\X.0

where X is the major version of PowerBuilder that you are creating the new item for (7, 8, or 9). Under that key create a new subkey called "CLSID" that all the new items will be located under (see Figure 1).

For each new item you want to add, create another new subkey under the CLSID key named with a globally unique identifier (GUID). A GUID is a 32-character value used within the Windows operating system to uniquely reference objects and has a format of {AAAAAAAA-BBBB-CCCC-DDDD-EEEEEEEEEEEE}. There are a number of different ways to generate GUIDs, including:

• Using GUIDGEN.EXE, a GUI utility that's provided with Microsoft Visual Studio (see Figure 2).

   

• Using UUIDGEN.EXE, a command-line utility that's provided with the Windows Platform Software Development Kit (SDK), which is available for free download from the Microsoft Developer's Network (msdn.microsoft.com) (see Figure 3).

   

• Alternatively, PowerBuilder is capable of generating GUIDs. If you have a nonvisual object in a PowerBuilder project and a Jaguar profile defined (even if it's not operational), you can fire up the COM/MTS/COM+ Component Wizard. The fifth screen in that dialog generates a GUID for the Interface ID for the component (see Figure 4).

  Once you've generated the first GUID for the first dialog item, you might want to just use sequential values from that point on (refer to Figure 1 again).

  After the CSLID entry has been created, you need to modify the default string value and create three new ones:

• (Default): The entry is automatically created when the CSLID entry is created. The value you provide for it will be the text that will appear in the New dialog under the new icon.
• DefaultIcon: This entry points to which icon to use in the new dialog. In addition to .ICO files, this can also point to an .EXE or .DLL file, followed by a comma and then a number that indicates which index to the icon within the EXE or DLL file to use. A number of utilities will show the icons within an EXE or DLL you might select, including the Change Icon dialog within the Windows Create Shortcut utility (see Figure 5). Remember the index is zero-based (the first icon in a DLL or EXE has an index value of 0, the next has an index of 1, etc.).
• URL: Create this entry to tell PowerBuilder what to run when the user selects the new icon. It can be one of the following:
  -Wizard (addressed below)
  -An Internet shortcut (http://, ftp://, or mailto:)
  -The name of one of the PowerBuilder painters or dialogs (Application://, Database://, DataWindow://, DBProfile://, DataPipeline://, Debug://, FileEdit://, Function://, Library://, Menu://, Project://, Query://, Report://, RunReport://, RunWindow://, Structure://, UserObject://, or Window://)

  The URL syntax follows the standard for Internet URLs in that the URL can be prefixed with username/password information and suffixed by a "?", followed by any arguments in a name/value combination. Arguments to painters can include "action" (where action can be "new," "inherit," "run," "runonly," and "open"), "path" (indicates the path to the PBL containing the object), and "entry" (indicates the name of the object).

• Tabpage: This entry indicates the tabpage that you want the new icon to appear on. You don't need to provide a value for the string value, just the name.
  -WorkspaceTool for the Workspace tabpage
  -StartTool for the Target tabpage
  -ObjectTool for the Object tabpage
  -WebTool for the Web tabpage
  -DataWindowTool for the DataWindow tabpage
  -DataBaseTool for the DataBase tabpage
  -ProjectTool for the Project tabpage
  -Tool for the Tool tabpage

  Listing 1 is a portion of a PowerBuilder utility, available in the source code, that will create these registry entries for you.

  The results are shown in Figure 6. Note that there does not appear to be any way to control the position of the new icon. Interestingly enough, they're added to the front of the dialog, not at the end, as I would have expected.

  Also note that the URLs indicated here will work in the custom toolbar icon dialogs as well. The main advantage of adding items to the New Dialog over the toolbar is that the toolbar doesn't allow you to use icons other than those provided with PowerBuilder.

  Creating Custom Wizards
  You may not realize it, but a number of the PowerBuilder system DLLs in the Shared/PowerBuilder directory are not actually DLLs. They're PBDs (compiled PowerBuilder libraries) that have simply been renamed. If you rename the extension on a copy of them to PBL and add the PBDs to a target, you can examine the object listing and even open the objects in the PowerBuilder IDE, but you won't be able to view the source for any scripts. In particular, the PBADD90.DLL appears to contain the many items provided with PowerBuilder on the tools tab of the new dialog (migration assistant, DataWindow syntax, profiling tools, PFC extender, etc.). The PBGEN90.DLL file appears to be the PowerBuilder objects used during template target generation. Finally, the PBWIZ90.DLL and PBWZP90.DLL files appear to be the PowerBuilder objects that serve as a basis for many of the wizards that appear with the PowerBuilder IDE.

  This illustrates the next method of extending the PowerBuilder IDE. It's possible to create objects within PowerBuilder that can then be used as wizards within the IDE. Once you've created the objects and compiled the library that contains them to a PBD, let the PowerBuilder IDE know about them through a couple of registry entries. First, navigate to HKEY_LOCAL_MACHINE\SOFTWARE\Sybase\PowerBuilder\X.0 again, and this time create a subkey called "WizardLibraries." Under that new subkey create new string values for each PBD you want to be able to use the objects from. The name of the string values must be a sequential number, and the value will point to the PBD file.

  Now that the objects are available to the PowerBuilder IDE, create a new dialog icon or custom toolbar icon that runs them, using the "wizard" keyword mentioned above. The "wizard" keyword syntax is as follows:

  wizard:?entry=

  where is the window you want the PowerBuilder IDE to run when the option is selected (without the brackets).

  The source code for this article includes a small utility for creating the WizardLibraries entry for you. Listing 2 provides the most relevant section of that application.

  Figure 7 illustrates a custom wizard running from within the PowerBuilder IDE. The sample code for this wizard is also included in the sample code for the article.

• Custom To-Do Lists
  Custom to-do lists were saved for last because they currently work only in PowerBuilder 7.x. The technique is still supported within the PowerBuilder IDE in later releases (8.x and 9.x); however, the to-do lists in PowerBuilder are actually PowerBuilder objects, and the statement used within them to load the custom to-do entries uses a form of dot notation that was broken with PowerBuilder 8.x and that has not been corrected to date in PowerBuilder 9.x. We'll still cover the technique though, in the hopes that Sybase will either fix that particular form of dot notation or at least modify the to-do list object to use a different method of loading the custom items in some future build.

  As you are probably expecting at this point, custom to-do list items are implemented by adding registry entries. Once again navigate to the HKEY_LOCAL_MACHINE\SOFTWARE\Sybase\PowerBuilder\X.0 key and add a new subkey called "CustomTo-Do". You then need to create another subkey under that indicating the wizard type you're adding the entry for, and then another subkey under the wizard type subkey to indicate which tab the wizard is run from. The valid values for Wizard Type include "template," "jaguar proxy," "jaguar component," "com component," and "ole auto component," and the valid values for the Wizard Tab are "start," "object," and "project."

  Finally, create string values underneath the last subkey that contains the items you want to have added to the to-do list that PowerBuilder already created. You can have a number of these, and they're added to the to-do list in alphabetical order for the string value name. Note that the value of the string value is a URL similar in format to what you used for custom items in the New Dialog, except you use a semicolon ";" rather than the ampersand "&". One additional argument, "text", is used to indicate the text that will appear in the custom to-do list for the entry.

  For example, if you wanted to add custom to-do list items after the template wizard was run from the Target tab (called the "start" tab internally), you would create the following registry key:

  HKEY_LOCAL_MACHINE\SOFTWARE\Sybase\PowerBuilder\7.0\CustomTo-Do\template\start

  and then add a string value similar to:

  name: 1
  value: http://www.teamsybase.com;text=Go to TeamSybase web page

  The sample code provided with this article includes a utility to create these entries for you. Figure 8 shows what this particular custom to-do list item looks like after the template application creation wizard has run.

  Note, however, that once a wizard runs, it adds the to-do list entries (regardless of whether you add custom ones) to the registry. Therefore, you can add custom to-do list entries by directly accessing the registry. To-do list entries are stored under a registry key of:

  HKEY_CURRENT_USER\SOFTWARE\Sybase\PowerBuilder\X.0\Application\
  $pbl-path(application-name)\ToDo

  where pbl-path is the path to the PBL containing the PowerBuilder application object for the application. Note that any \ or / characters in the pbl-path entry are encoded as $ characters. The string values underneath that subkey include the to-do list items as well as two additional items: count (the number of items in the list) and selection (the last item the user worked on). The format for the string value for the to-do list items in this section of the registry begins with a "y" or "n" character (indicating whether the item is checked), followed by a tab, the text shown to the user, another tab, and then the URL for the action.

  As a result, it's certainly possible to add items to any existing to-do list by adding items directly to the registry. However, this approach will not result in the items being added automatically when the wizards are run, which the previous approach does.

  Conclusion
  Now you know a few other methods for customizing the PowerBuilder IDE. Note that Sybase has indicated their desire to open up the IDE to make it more accessible for plug-ins and other customizations. Hopefully what you've learned here is just the tip of the iceberg with regard to what you will be able to control in the new versions coming soon.

--This article was originally published on PBDJ.