Tivoli Service Desk 6.0 Developer's Toolkit Script Programming Guide
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:
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.
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);
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.
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.
You can create the application main window in TSD Script. In TSD Script, creating a window involves the following steps:
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:
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:
- First, it creates a list of icon names.
- Then it uses WinSetIconBar to send a message to the window that is about to be created, and tells it to add these icons to its tool bar. For example:
EVENT MainEvent(REF context: ContextRecord) IS VARIABLES iconList: List of String; ACTIONS WHEN $Event IS $MsgCreate THEN iconList:={'ADDINV.ICO','SRCHINV.ICO', 'REPORTS.ICO'): LIST OF STRING; WinSetIconBar($Handle,iconList); ELSWHEN $MsgSelect THEN WHEN $EventParm(1,Integer) IS 1 THEN CreateAddWindow; ELSWHEN 2 THEN CreateSearchWindow; ELSWHEN 3 THEN CreateReportWindow; END; ELSWHEN QUERY_CURRENT_ID THEN $EventParm(1,String):=context.current_ID; END; END (* Main Event *);
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.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:
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);
Using '/L-' indicates that a separator should appear between menu commands.
WinSetMenuBar($Handle,{'File','New','Open',..., '/L-', 'General Help'}: LIST OF STRING);
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.
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.
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. |
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. |
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.
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.
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 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.
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. |
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