Creating the PowerBuilder application

The starting point of your PowerBuilder window plug-in application
is a child window displayed in a Web page. In the window you can
include controls and write scripts for events. Your scripts can
open other windows, read and write files, and run other programs
on the client machine.

Design choices for plug-in applications

The application you design for use as a plug-in can be much
the same as other PowerBuilder applications you develop, but there
are some restrictions and considerations to keep in mind in the
following areas:

• Window management
• Objects
• Scripts and variables
• Data access
• External files

Window management

Initial child window Your initial window needs to be a child window that lives
in the browser frame.

You can:

• Include a title bar on the child window (but you should
  not use a control menu, maximize box, or minimize box
  on that window)
• Open pop-up and response windows from the child
  window (but not main or MDI windows)

You cannot:

• Have a menu for the child window
• Open another child window from the initial window

Closing windows When the client browses to another Web page, the child window
on the current Web page is closed, but other windows remain open unless
your application closes them. You must close them in the child window’s
Close or CloseQuery events.

Do not try to stop the child window from being closed in the
CloseQuery event by setting a return value. You cannot prevent the
browser from changing to another page and removing the window from
view. If the user returns to the page, another instance of your
application is started.

Objects

Objects in your PBDs Your plug-in application has access to all objects in the
PBDs. This includes functions, structures, and user objects.

System objects Your plug-in application has access to system objects that PowerBuilder
instantiates, such as the SQLCA Transaction object and the Message
object.

Application object You can use the optional APPLICATION attribute of the Embed
element to specify the name of your PBD’s Application object.
This gives your plug-in application access to the Application object’s
Open and Close events.

If you do not specify the APPLICATION
attribute:

• Your plug-in application does not
  have access to the Application object, and thus events like SystemError
  and Idle are not available. You cannot treat variables and functions
  defined in an Application object as global.
• Any scripts in the Application object are used only
  during testing within PowerBuilder. You cannot do any application
  setup in the Application object’s scripts.

For information about specifying the APPLICATION
attribute, see “Attributes of the Embed
element”.

Scripts and variables

Global variables If you use the APPLICATION attribute of the Embed element
to specify your PBD’s Application object, your plug-in
application has access to global variables and global functions
used in the application.

If you do not specify the APPLICATION
attribute, the plug-in application cannot use global variables.
You must define all variables as instance, shared, or local.

For information about specifying the APPLICATION
attribute, see “Attributes of the Embed
element”.

Referencing the initial window You cannot reference the initial child window by name in your
scripts, because PowerBuilder does not create a variable to hold
the instance of it. (By contrast, when you instantiate a window yourself
by coding the Open function, you always place
the instance in a variable that you can then reference.)

Thus, the following code produces an error at runtime (because
the window variable w_mychild does
not exist):

But you can code:

Scripts for application setup All application setup must be done in the child window, including
connecting to the DBMS. The first scriptable events to occur are
the constructors for the controls in the window. Then the Open event
for the window occurs.

The Activate event does not occur for a child window; do not
put application setup code there.

Data access

If your application accesses a DBMS, each client must have
a connection to the data source. The connection must be defined
on the client’s machine, not the server. The data source
might be a local or a network DBMS.

For information about how to connect to a
DBMS from the client machine, see Connecting to Your Database
.

The constructor events for controls occur before the Open
event of the window. If you connect to the DBMS in the window’s
Open event, the constructor events cannot get data. You can get
data for controls in the window’s Open event, or you can
post events from the constructor events or the window’s
Open event.

Paths for external resources

Paths you specify for files must be valid on the client workstation.

If your application uses images as external files, the images
must be available at the path specified in the PowerBuilder object.
Instead of using external files, you can build image resources into
PBDs, as described in “Building the dynamic
libraries”.

If your application reads or writes local files, the path
for those files must be valid on each client’s machine.

If a path refers to a network drive by mapped drive letter,
all clients must use the same drive letter that the application
uses. As an alternative, specify the server name in the path instead.

For example, both of these paths are valid when o: is
mapped to \marketingdrive,
but the second path, which uses a server name, is more likely to remain valid.

Defining the starting window in the Window painter

You use the Window painter to create the starting window,
as you do for any window you create in PowerBuilder.

To create your application’s starting
(or only) window:

1. Create a new window object in PowerBuilder.

2. On the window’s General tab of the Properties
   view, set the window type to child.

3. Add other controls as needed.

4. Write scripts for events of the window and controls.

To convert an existing application to run as a
plug-in:

1. Change the type of the opening window to
   child.

2. If you do not plan to specify
   the APPLICATION attribute of the Embed element, do both of the following:

   • Remove references to global variables.
   • Move application setup code from the application’s
     Open event or MDI frame events to the child window’s Open
     event.

   For information about specifying the APPLICATION
   attribute, see “Attributes of the Embed
   element”.

3. Depending on the application’s design,
   you may need to redesign how it opens other windows.

About child windows

Child windows cannot have menus. They are never considered
the active window–and therefore the Activate event is never
triggered. They can have title bars and can be minimized, maximized,
and resized. In the plug-in environment, the child window is always
restricted to the space allotted by the WIDTH and HEIGHT attributes
specified on the Web page, as follows:

• Maximizing causes the window to fill the space allotted
  by the WIDTH and HEIGHT attributes.
• Minimizing displays the window’s icon and
  title at the bottom of the plug-in’s allotted
  space.
• If the child window is resizable, the user can drag
  the borders to make the window smaller (but not larger) than the
  allotted space.

As a result, it is not useful to allow minimizing, maximizing,
or resizing of the child window.

Testing the application in PowerBuilder

Before you try your application in a client browser, you can
test it in PowerBuilder by defining a main window that opens the
child window.

To test your PowerBuilder window plug-in application:

1. Create a new window object whose type is
   main (the default).

2. Write a script for the Open event that opens the
   plug-in’s starting child window:

   PowerBuilder

   Open(w_child)

   1	Open(w_child)

3. For convenience, you can set appropriate window
   sizes in the Window painter:

   • Make
     the main window large enough to display the child
   • Position the child window in the upper-left corner
     (use the Position fields in the Other tab of the Properties view)

4. Run the test window by clicking the Preview button
   or selecting File>Run/Preview.

Debugging in PowerBuilder To use the PowerBuilder debugger, you need to run an application
instead of a single window. Define an Application object with a
script that opens the main window. Then you can use the Run or Debug
command to test the application.

Building the dynamic libraries

The User’s Guide
describes how
to build dynamic runtime libraries (PBDs). The procedure is the
same for a plug-in application. This section highlights the choices
you need to make for building a PBD for a plug-in application.

Remember that in the Web environment, file size is important.

Organizing objects in PBLs

Before you build your application, you should use the System
Tree or Library painter to organize the objects your application
uses in PBLs, which are the sources for the plug-in application’s
PBDs. The following suggestions can help you optimize the resulting
libraries:

• To minimize file
  size, include only objects the application uses; remove any objects
  that are not needed.
• Include any objects that are dynamically created,
  such as DataWindow objects used in DataStores or assigned dynamically
  to DataWindow controls.
• Include ancestor objects.

Using PowerBuilder resource (PBR) files

Several controls can use external files for images. These
include PictureListBox, TreeView, Picture, and PictureButton controls,
pointers, and bitmap objects in DataWindow objects. If your application
uses external files for the images, it is unlikely that the client
has the same images on the same system path.

Instead of finding some way to install the pictures on client
machines, you can use one or more PowerBuilder resource (PBR) files
so that the images are built into the PBDs. The resulting PBDs are
larger but self contained.

Because you are building a dynamic runtime library, not an
executable, you do not need to include DataWindow objects in the
PBR file. All PowerBuilder objects in the source PBL are included
in the resulting PBD.

Images and other resources on a network Instead of building the files into the PBD, you can put the
files in a generally accessible network directory, but the path
to the files must be identical to the path named in the PowerBuilder
objects. This means that in the Windows environment, each client
must use the same drive letter to map the network drive, or you
can specify the server name in the path.

To define a PBR file:

1. Open the PowerBuilder File Editor (Shift+F6)
   or some other text editor and create a new file with the extension
   PBR. (You can add the File Editor icon to the toolbar.)

2. List each image or other resource on its own line.
   List the path and file name exactly as it is named in the object
   property sheet or script.

   Shortcut Look at the object’s Properties view and use Ctrl+C
   to copy the file name to the clipboard, then paste it into the editor.

3. Save the file.

If your application includes several PBLs, each with objects
using their own resources, you should create a PBR file for each
PBL. The PBR file will list file names for resources that are used
in one PBL.

Building the PBDs

Build your runtime libraries (PBDs) in the Project or Library
painter as described in the User’s Guide
.
Keep in mind:

• Deselect Machine
  code Your plug-in application must have PBDs, not machine code
  DLLs.
• Specify a PBR file for each PBD If the objects in the PBL use resources that you have listed
  in a PBR file, put the PBR name in the Resource File Name text box.

For instructions on defining a PBR file and
building your runtime libraries (PBDs), see the chapter on creating
an executable in the User’s Guide
.

---