Tivoli Service Desk 6.0 Developer's Toolkit Script Programming Guide

Chapter 6: Using the TSD Script Window System

Back to Table of Contents


Introduction

Using TSD Script, you can create generic windows, virtual scroll windows, and forms. The TSD Script window system is composed of a number of TSD Script statements that allow you to create a custom user interface.

This chapter:

Window description

A window is a portion of a screen or desktop that contains its own document or message. The following terms are used to describe the parts of a generic window.

Using WinCreate

Creating a generic window

WinCreate is used to create generic windows. A generic window is the most simple and flexible window provided by TSD Script. Generic windows can also contain their own messages.

VARIABLES 
  mainWindow: Window; 
ACTIONS 
  WinCreate($Desktop,mainWindow,MainEvent, 
            1,1,100,30,'',0); 

Example WinCreate arguments

The following explanation describes the WinCreate arguments used in the actions section of the preceding example:

The coordinate system begins with (1,1) located at the upper left-hand corner of the screen. X-coordinates increase to the right; y-coordinates increase as they move down the screen.

The next two arguments are the width and height (respectively) of the new window's client area. These are in character units.

The window created in the example has its upper left-hand corner on the upper left-hand corner of the screen. It is 100 characters wide and 30 characters high.

Using creation flags

In the following example, the last argument is an integer expression where each bit position represents an on/off flag. For example:

WinCreate($Desktop,mainWindow,MainEvent, 
          1,1,100,30,'',
          BitOr($WinTitle,$WinBorder,$WinMinMax)); 

The result of the BitOr function means that this window is created with three items: a title bar, a border, and a set of minimize/maximize buttons in the upper right-hand corner.

For detailed information about the creation flags provided by TSD Script, refer to the TSD 6.0 Developer's Toolkit Script Language Reference.

Creating a window

You can create the application main window in TSD Script. In TSD Script, creating a window involves the following steps:

  1. The event handler associated with the window is called with a $MsgSize event. This occurs before the window is drawn on the screen.
    In addition, two other pieces of information are passed to the event handler: the width and height of the new window, expressed in characters. These values are passed in the first unnamed event parameter (INTEGER) and the second unnamed event parameter (INTEGER), respectively.
  2. The event handler is then called with a $MsgCreate event. This signals the event handler that the window is about to be drawn on the screen. At this point, the event handler should perform actions to add menu commands, tools, and other visual elements.

Note: If the event handler performs actions that change the size of the client area of the window, a new $MsgSize message is generated. The client area of a window is the area where an end user works. Elements that are not included in the client area include the:

  1. The window frame is drawn on screen.
  2. The event handler is called with a $MsgPaint message. At this time, the event handler must draw any other information that appears inside the client area of the window.

Of these four steps, most windows are concerned only with the second and the fourth. The $MsgCreate message is important because it identifies the appropriate time for the event handler to make final adjustments to the window before it is displayed and to initialize values in the instance data.

When the MainEvent routine receives the $MsgCreate message, it performs two actions:

Note: The $WinIconBar flag in the main program's WinCreate statement determines that the new window is sized correctly so that the client area is correct when the tool bar is added.

Drop-Down Menus

Creating a drop-down menu system

This section discusses how to create a menu system. Imagine that you want to construct a menu system with three menus: File, Edit, and Help. Under the File menu there are the following commands:

Under the Edit menu there are the following commands:

Finally, there are the following Help menu commands:

Menu options

The two-dimensional menu structure is translated into a one-dimensional list by adding options top to bottom, left to right.

ListInsert(menuList,''); 
ListInsert(menuList,'Save ~As'); 
WinSetMenuBar($Handle,{'File','New','Open',...,
'General Help''}: LIST OF STRING); 
WinSetMenuBar($Handle,{'File','New','Open',..., '/L-',
'General Help'}: LIST OF STRING);


Event parameters and menu commands

When the user selects a menu command, the event handler for the window receives a $MsgMenu message. The first $MenuSelection event parameter (INTEGER) contains an integer that indicates the menu command selected. This integer is coded as:

major*100 + minor 

Major is the number of the horizontal menu command selected (100 for the left-most), and minor is the number of the vertical menu command selected (101 for the top). So, if the user chose the Paste command under the Edit menu, the first unnamed event parameter (integer) would have the value 203 because Edit is the second horizontal command and Paste is the third vertical command. The numbers 1-99 represent tools, because tool events are also handled by $MsgMenu.

Generic Windows

Cursor position in a generic window

TSD Script provides a number of statements that alter the appearance of the client area of a generic window. Internally, generic windows keep track of a current cursor position. This is an (x,y) position where certain output operations (such as WinWrite) occur.


The drawing position in the currently selected coordinate system can be measured from position (1,1), which is at the top left-hand corner of the client area. The drawing position can be measured in:

X-coordinate positions increase to the right and y-coordinate positions increase downward.

Window statements

The statements that can be used with generic windows are listed in the table that follows. Parameters are listed in the Tivoli Service Desk 6.0 Developer's Toolkit Script Programming Guide.

Statement Description
WinGoToXY Moves the current position to a given (x,y) coordinate.
WinWrite Writes a string at the current position.
WinWriteAt Writes a string at a given position.
WinWriteLN Writes a string at the current position and advances the position pointer to the beginning of the next line.
WinX Returns the x-coordinate of the current text output.
WinY Returns the y-coordinate of the current text output.
WinWidth Returns the width of the window in characters.
WinHeight Returns the height of the window in coordinates.
WinClear Clears the entire window to the current background color.
WinClearEOL Clears the window to the current background color (beginning from the current cursor position to the end of the current line).
WinClearEOW Clears the window to the current background color (beginning at the right of the current cursor position and going to below the current cursor position).
WinClearRectangle Clears a given rectangular region to the current background drawing color.
WinGetXPos Returns the x-coordinate position of a valid window handle.
WinGetYPos Returns the y-coordinate position of a valid window handle.
WinSetColor Sets the current foreground and background drawing colors for the window.

Window creation statements

The following statements are functions used to create windows.

Statement Description
WinSetIconBar Sets the contents of the icon bar.
WinSetMenuBar Sets the contents of the menu bar.
WinCreateClock Creates a clock or timer window within the generic window.
WinCreateImage Creates an image viewer within the generic window that displays a given image file.
WinCreateMouseRect Creates a rectangular "hot spot" on the window at a given location. Mouse clicks in this region generate events for the generic window's event handler.

Repainting generic windows

The $MsgPaint event (also referred to as a repaint message) indicates that some portion of the generic window needs to be redrawn.

If a user closes another window or clicks the generic window, the window manager needs to redisplay the contents of the generic window. It does this by sending the $MsgPaint message. Since the window manager does not remember the contents of each window that opens on the desktop, it expects that each window knows how to repaint itself.

For instance, suppose that:

If a user clicks on that other window, it comes to the foreground and part (or all) of your generic window drops behind it. To update the display, both windows must repaint themselves.

An event handler can receive a $MsgPaint message for a window it services at any time. There are two basic triggers that result in the repaint message:

Note: In general, generic windows that write to the client portion of the window should do so only in the part of the event handler that services the $MsgPaint event.

Virtual Scroll Windows

Generic windows must be able to handle repaint messages and regenerate their own contents at any time. TSD Script provides a virtual scroll window that does the following:

A virtual scroll window is fully virtual. You can write information anywhere in its two-dimensional space and use the scroll bars (horizontal and vertical) to view it.

Note: A virtual scroll window knows nothing about the structure of your data. It is easier to use than a generic window, but may be less efficient.

Creating a virtual scroll window

A virtual scroll window is created with the WinCreateScrollWindow statement. This statement takes the following arguments:

Argument Name Description
whdlParent The handle for the parent of a newly created window.
whdl The handle of the newly created window is returned in this parameter. If there is an error, the variable is set to $Unknown.
EventHandler An event handler to process events generated by the window or dialog box. If no event processing is required, the keyword $NullHander may be used.
xLoc The X location of the upper left corner of the window. X coordinates are measured in character cells.
yLoc The Y location of the upper left corner of the window. Y coordinates are measured in character cells.
width The width (X dimension) of the window, excluding border. X coordinates are measured in character cells.
height The height (Y dimension) of the window excluding border, title bar, menu bar, icon bar, and status bar. Y coordinates are measured in character cells.
title The title to display on the window title bar. The window must have a title bar for a title to be displayed. Use the $WinTitle style.
font The name of an available system font.
pointSize The point size of the font to be used within the scroll window.
style An integer bit mask that represents a list of style flags used to control the window's appearance.

Virtual scroll window example

Virtual scroll windows are useful for recording "line-at-a-time" information. The following example creates a window that serves as a scrollable "black board." The window is used to list the names and social security numbers of all the employees in the EMPLOYEES table. These names and numbers are written into the window a line at a time, starting at the top of the window.

VARIABLES 
  vWin: Window; 
  i: INTEGER; 
  cursor: SQLCursor; 
ACTIONS 
  WinCreateScrollWindow($Desktop,vWin,$NullHandler,
                        1,1, 80,25,'Matches',
                        SystemMonospaced, 10,
                        BitOr($WinDefaultStyle,
                              $WinViscroll,
                              $WinAutoScroll)); 
  i:=SQLSelect(cursor,'SELECT * FROM EMPLOYEES'); 
  WHILE i > 0 DO 
    i:=SQLFetch(cursor,employee); 
    IF i > 0 THEN 
    WinWriteLn(vWin,employee.first_name & ' ' & 
             employee.last_name & ' ' & employee.ssn); 
    END; 
  END; 
  SQLCloseCursor(cursor); 

Because the $WinAutoScroll style is used, earlier entries scroll off the top of the window when the bottom of the window is reached.

You can use the vertical scroll bar at any time to go back and see earlier entries. When a user finishes with the window, he or she can close it with the system menu or a $MsgClose message can be sent explicitly in the application.

Virtual scroll window statements

The following statements can be used to change the appearance and function of a virtual scroll window:

Statement Name Description
WinGoToXY Moves the current position to a given virtual (x,y) coordinate.
WinWrite Writes a string at the current position.
WinWriteAt Writes a string at a given position.
WinWriteLN Writes a string at the current position and advances the position pointer to the beginning of the next line. If the current position is at the bottom of the window, and you use the $WinAutoScroll style, the entire window is scrolled up one line .
WinX Returns the x-coordinate of the current text output position.
WinY Returns the y-coordinate of the current text output position.
WinWidth Returns the width of the (physical) window in characters.
WinHeight Returns the height of the (physical) window in coordinates.
WinClear Clears the entire window to the current background color.
WinClearEOL Clears the virtual window from the cursor position to the end of the current line to the current background color.
WinClearEOW Clears the window to the current background color (beginning at the right of the current cursor position and going to below the current cursor position).
WinClearRectangle Clears a given rectangular region to the current background color.
WinSetColor Sets the current foreground and background drawing colors for the window.
WinSetIconBar Sets the contents of the icon bar.
WinSetMenuBar Sets the contents of the menu bar.
WinCreateClock Creates a clock or timer window within the scroll window. The clock automatically scrolls inside the scroll window.
WinCreateImage Creates an image viewer within the scroll window that displays a given image file. This image automatically scrolls inside the scroll window.
WinGetXPos Returns the x-coordinate position of a valid window handle
WinGetYPos Returns the y-coordinate position of a valid window handle.
WinCreateMouseRect Creates a rectangular hot spot on the window at a given location. Mouse clicks in this region generate events for the scroll window's event handler.

Cursor position

Like generic windows, virtual windows maintain an internal cursor (x,y) position. This cursor position indicates where certain output operations (such as WinWrite) begin. After a WinWrite operation, the cursor's x-position is incremented by the number of characters written.

The cursor position can be found by calling the WinX and WinY functions. The cursor position can be changed by calling the WinGotoXY( ) function.


Tivoli Service Desk 6.0 Developer's Toolkit Script Programming Guide

Back to Table of Contents

Copyright