Tivoli Service Desk 6.0 Developer's Toolkit Script Language Reference

Window Handling

Return to Main Page


Note: All Win functions have the same return codes. This table of codes appears in the WinAboutBox function and a link to this table appears with every Win function.


Return to Main Page


Note: This is the first section of Window Handling functions. This section ends with WinSetColor, while the second section begins
with WinSetFont.


$Desktop

Description

Returns a handle to the desktop window. This value is permanent during the current session. This value is not stored permanently, however. The next time the program executes, this constant has a new value.

Syntax

FUNCTION $Desktop: WINDOW;

Caution: In OS/2, there are valid messages you can send to the desktop to pause processing. For example, sending $MsgClose to the desktop pauses the running of the program. This behavior is controlled by the operating system.

Notes

$Desktop is a predefined system constant that contains the handle to either the OS/2 desktop or the Windows desktop. It is often specified as the parent in window and dialog box statements.

Example

KNOWLEDGEBASE Desktop;
ROUTINES
 PROCEDURE Example;
PRIVATE
ROUTINES
 (* Create a scroll window parented by the desktop with
 default event processing *)
PROCEDURE Example IS
 VARIABLES
 whdl: WINDOW;
ACTIONS
 WinCreateScrollWindow($Desktop, (*Window is a child of
                       OS/2 desktop *)
                       whdl, (* return handle
                       of new window *)
                       $NullHandler, (* Default event
                       processing *)
                       5, 5, 80, 20, (* Window location
                       and size *)
                       'Example', (* Window title *)
                       '', (* Use default font
                       *)
                       0, (* Point size is
                       ignored for
                       default *)
                       BitOr( $WinTitle, $WinBorder,
                       $WinSysMenu ));
 WinWait( whdl );
END;

See Also


$KeyCode

Description

Indicates the key pressed by the user when a $MsgChar event occurs.

Notes

TSD Script defines several constants for special keys such as the cursor control keys, modified keys (i.e., keys that are pressed in combination with others, such as Control or Alt), etc.

Note: For more information, see TSD Script Constants.

Example

EVENT MyEvent IS
ACTIONS
WHEN $Event IS $MsgChar THEN
 WHEN $KeyCode IS $KeyUpArrow THEN
 MoveUp;
 ELSWHEN $KeyDownArrow THEN
 MoveDown;
 ELSWHEN $KeyLeftArrow THEN
 MoveLeft;
 ELSWHEN $KeyRightArrow THEN
 MoveRight;
 END;
END;

See Also


WinAboutBox

Description

This function displays a default "About" box for an application.

Syntax

FUNCTION WinAboutBox( VAL Icon : STRING,
                     VAL AppName : STRING,
                     VAL Version : STRING ) : INTEGER;

Cautions

The information displayed contains a Tivoli Service Desk copyright message and is not intended for third party applications.

Argument Notes

Argument Name Description
Icon The name of the associated .bmp file to display with your
application. If the file can not be found or the filename is invalid, the box is displayed without a graphic. The SAIPATH and PATH environment variables are searched for files specified by this command.
AppName The name of your application.
Version The version number of your application.

Example

KNOWLEDGEBASE aboutbox;
CONSTANTS
AppName IS 'Pink Elephant Word Processor'; AppVersion IS
 'Version 3.1';
ROUTINES
Procedure DisplayAboutBox;
PRIVATE
ROUTINES
Procedure DisplayAboutBox IS
VARIABLES
ACTIONS
WinAboutBox('pink.bmp', AppName, AppVersion);
END;

Return Codes

Return Code Description
1 Successful completion.
0 User abort. The user closed the window or aborted the operation. Usually this is done by pressing the Esc key or the Cancel button, or by closing the window from the system menu.
-1 The window handle does not refer to a valid window. The window may no longer exist, or the window does not support the command.
-2 Unknown value.
-3 Insufficient memory.
-4 No creation. The operating system was unable to create the requested object. One possible cause is that a parent window handle references a window that no longer exists.
-7 The named control of a dialog box could not be found in the dialog box referenced by the window handle.
-8 The requested dialog box command may not be performed on the type of control named.
-10 A call failed at the operating system level. This may be caused by an improper configuration or inadequate resources.
-12 The SendMessage or PostMessage statement was called with a message that is not supported by the NETx statements. Messages must either be one of the supported $MsgNetx messages or a user-defined $MsgUser + n message that is specifically defined for use with the NETx statements.

WinClear

Description

Clears the entire client area of a window or a scroll window to the current background color.

Syntax

FUNCTION WinClear(VAL whdl: WINDOW): INTEGER;

Argument Notes

Argument Name Description
whdl The handle of the window to be cleared. This handle may refer to a standard window or a scroll window.

Notes

The current background color can be changed using the WinSetColor function.

Example

WHEN $Event IS $MsgPaint THEN
 WinSetColor($Handle,$WinWhite,$WinBlack);
             WinClear($Handle);
             WinWrite($Handle,'Black');

Return Codes

See Also


WinClearEOL

Description

Clears a window from the current cursor position to the end of line, using the current background color.

Syntax

FUNCTION WinClearEOL(VAL whdl: WINDOW): INTEGER;

Argument Notes

Argument Name Description
whdl The handle of the window to be cleared. The handle may refer to a standard window or a scroll window.

Notes

WinClearEOL clears from the current cursor position to the end of the current line. It does not change the cursor position. The area cleared is painted in the current background color.

Note: The current background color can be changed using the WinSetColor function.

Example

WHEN $Event IS $MsgPaint THEN
 WinSetColor($Handle,$WinWhite,$WinBlue);
             WinGoToXY($Handle,2,2);
             WinClearEOL($Handle);

Return Codes

See Also


WinClearEOW

Description

Clears the window from the current cursor position to the bottom of the window, using the current background color.

Syntax

FUNCTION WinClearEOW(VAL whdl: WINDOW): INTEGER;

Argument Notes

Argument Name Description
whdl The handle of the window to be cleared. This handle may refer to a standard window or a scroll window.

Notes

WinClearEOW clears the indicated window from the current cursor position to the end of the window. The area cleared is painted the current background color. The cursor position is not changed.

Note: The current background color can be changed using the WinSetColor statement.

Example

WHEN $Event IS $MsgPaint THEN
 WinGoToXY($Handle,5,10);
 WinSetColor($Handle,$WinWhite,$WinLightBlue);
 WinClearEOW($Handle);

Return Codes

See Also


WinClearRectangle

Description

Clears a rectangular region of a window, using the current background color.

Syntax

FUNCTION WinClearRectangle(VAL whdl: WINDOW, VAL xLoc, yLoc,
                           width, height: INTEGER):
                           INTEGER;

Argument Notes

Argument Name Description
whdl The handle of the window to be cleared. The handle may refer to a standard window or a scroll window.
xLoc The X location of the upper left corner of the region to be cleared. X coordinates are specified character cells.
yLoc The Y location of the upper left corner of the region to be cleared. Y coordinates are specified in character cells.
width The width of the region to be cleared. Width is measured in character cells.
height The height of the region to be cleared. Height is measured in character cells.

Notes

WinClearRectangle clears a specific rectangular region within a given window. The region cleared is painted with the current background color. The cursor is not moved.

Note: The current background color can be changed using the WinSetColor statement.

Example

WHEN $Event IS $MsgPaint THEN
 WinSetColor($Handle,$WinWhite,$WinBlack);
 WinClearRectangle($Handle,5,10,40,8);
END:

Return Codes

See Also


WinCloseWindow

Description

Closes a dialog box or window.

Syntax

FUNCTION WinCloseWindow(VAL whdl: WINDOW): INTEGER;

Argument Notes

Argument Name Description
whdl Handle of the dialog box or window to be closed

Notes

This function is also implemented as a message that can be passed to a dialog box or window ($MsgClose).

Example

KNOWLEDGEBASE close;
ROUTINES
 PROCEDURE Main;
PRIVATE
ROUTINES
PROCEDURE Main IS
VARIABLES
 Handle : WINDOW;
ACTIONS
 WinCreate($Desktop,
 Handle,
 $NullHandler,
 1, 1,
 80, 25,
 'Window will close shortly...',
 $WinDefaultStyle);
 SysDelay(1000);
 WinCloseWindow(Handle);
END;

Return Codes


WinCreate

Description

Creates a standard or generic window.

Syntax

FUNCTION WinCreate(VAL parent: WINDOW, REF whdl: WINDOW,
                   VAL EventHandler: EVENT,
                   VAL xLoc, yLoc, width, height: INTEGER,
                   VAL title: STRING, style: INTEGER):
                   INTEGER;

Cautions

If the event function does not process the paint message and clear the window, the window retains an image of what was under it at the time of the window's creation.

WinCreate does not return until after $MsgCreate is processed. Therefore, the value of the returned window handle is not set until after $MsgCreate is processed. However, $Handle can still be used during the processing of WinCreate.

Argument Notes

Argument Name Description
parent Parent of the new window to be created.
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 that processes events generated by the window or dialog box. If no event processing is required, the keyword $NullHandler can be used.
xLoc The X location of the upper left corner of the window. X coordinates are specified in character cells.
yLoc The Y location of the upper left corner of the window. Y coordinates are specified in character cells.
width The width (X dimension) of the window, excluding border.
height The height (Y dimension) of the window excluding border, title bar, menu bar, toolbar, and status bar.
title The title displayed on the window title bar. The window must have a title bar for a title to be displayed. Use a style containing $WinTitle.
style An integer bit mask that represents a set of style flags used to control the window's appearance.
For a list of the available style flags, see Window Styles.

Notes

First Messages Received

When a window is created, the following messages are received in the order shown:

Customizing a Window with Styles

WinCreate can be used to create standard or generic windows. Such windows can contain menus bars, toolbars, status bars, and other window elements.

The exact appearance and behavior of the window created with WinCreate is largely determined by the style argument. This integer argument is a bit mask assembled from various flags (listed in the following section). The argument is usually assembled with the BITOR operator (for example, BITOR($WinBorder, $WinTitle)). The addition method should be used with caution; it may cause undesired results if the same flag is added twice.

Note: For more information, see Window Styles.

Creating an Event Handler for a Window

In general, you associate an event handler with a window created via WinCreate. An event handler is a routine that processes some of the messages sent to the window. For example, if the window has an icon bar, its event handler receives $MsgMenu messages (events) each time the user clicks one of the icons. The first event parameter (integer) contains a number between one (1) and the number of icons, indicating which icon was selected. The event handler can then call a particular routine.

Note: The various messages that can be received by windows created with WinCreate are documented in TSD-Script Messages.

Example

EVENT MainEvent IS
ACTIONS
WHEN $Event IS $MsgCreate THEN
 WinSetIconBar($Handle,{'FILE.ICO',
               'REPORT.ICO','HELP.ICO'}:
               LIST OF STRING);
ELSWHEN $MsgMenu THEN
 WHEN $EventParm(1,INTEGER) IS 1 THEN
 HandleFileIcon;
 ELSWHEN 2 THEN
 HandleReportIcon;
 ELSWHEN 3 THEN
 HandleHelpIcon;
 END;
END;
END;
PROCEDURE MainProgram IS
VARIABLES
mainWindow: WINDOW;
ACTIONS
WinCreate($Desktop,mainWindow,MainEvent,0,0,80,20,
 'Main Window',
 BitOr($WinBorder,$WinTitle,$WinResize,
 $WinSysMenu, $WinIconBar,
 $WinAutoPos,$WinTaskList));
WinWait(mainWindow);
END;

Return Codes

See Also


WinCreateClock

Description

Creates a clock or timer window.

Syntax

FUNCTION WinCreateClock(VAL whdlParent: WINDOW,
                        REF whdl: WINDOW,
                        VAL xLoc, yLoc, width, height, style,
                        id: INTEGER): INTEGER;

Argument Notes

Argument Name Description
whdlParent The parent of the new window to be created.
whdl The handle of the new window is returned in this parameter. If there is an error, the variable is set to $Unknown.
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. Width is measured in character cells.
height The height (Y dimension) of the window excluding border, title bar, menu bar, toolbar, and status bar. Height measured in character cells.
style The style of the clock window. Style flags are combined with the BITOR operator.
Select one or none from the following:
  • $ClkBorderIn - Draws the clock window with a recessed border (the default).
  • $ClkBorderOut - Draws a raised border.
  • $ClkBorderNon - Draws no border.
  • $ClkBorder - Draws a border similar to that of a text box.

Select one or none from the following:

  • $Clk12Hour: 12-hour format with AM and PM (the default).
  • $Clk24Hour: (24-hour format).

Optional flag: $ClkHidden - Clock is not displayed on screen.

ID Identification number used in notification messages to parent window. You can create timers in generic windows using the $MsgStartTimer message.

Notes

WinCreateClock can be used to create clocks that update themselves in real time (every second). By default, a clock begins displaying the current time of day based on the system clock. You can, however, set a clock to display a current time by sending it the $MsgClockSet message along with a time value.

For example, the following line could be used to set up an elapsed time clock:

SendMessage(clockWindow,$MsgClockSet,{0,0,0}: TIME);

Clock windows also respond to $MsgShow messages. This allows you to create a clock window, hide it, change its time value, and then show it. Consider the following example:

WHEN $Event IS $MsgCreate THEN
 WinCreateClock($Handle,clockWindow,
 1,1,13,2,
 $Clk24Hour,0);
 SendMessage(clockWindow,$MsgShow,FALSE);
ELSWHEN START_TIMER THEN
 SendMessage(clockWindow,$MsgClockSet,
 {0,0,0}: TIME):
 SendMessage(clockWindow,$MsgShow,TRUE);
END;

In this example, you are within the event processing for another window. When the window is created, it creates a clock but hides it. When the window receives a START_TIMER message, it sets the clocks time to 00:00:00 and then shows the clock. The user sees an elapsed time clock.

Example

VARIABLES
clock: WINDOW;
ROUTINES
EVENT WindowEvent IS
ACTIONS
 WHEN $Event IS $MsgCreate THEN
 WinCreateClock($Handle,clock,1,1,13,2,$ClkBorderIn,1);
 END;
END;

Return Codes

See Also


WinCreateHyperViewer

Description

Creates a Multiple Document Interface (MDI) viewer window that has basic hypertext capability. The menu bars available with the File, Edit, and Window menus allow you to:

Pop-up menu selections can be accessed by pressing the right mouse button in a hypermedia viewer. These menu items allow you to select:

Syntax

FUNCTION WinCreateHyperViewer(VAL whdlParent: WINDOW,
                              REF whdl: WINDOW,
                              VAL fileName: STRING,
                              VAL EventFunc: EVENT,
                              VAL xLoc, yLoc, width, height:
                              INTEGER,
                              VAL title: STRING,
                              VAL style: INTEGER): INTEGER;

Argument Notes

Argument Name Description
whdlParent The parent of the new window to be created.
whdl The handle of the newly created window is returned in this parameter. If there is an error, the whdl argument is set to $Unknown.
fileName The name of the file to be viewed. If the file is not in the current directory, the SAIPATH is searched. The file may be a plain ASCII file or it may have embedded hypertext links.
See the Notes section for further information.
EventFunc An event handler to process events generated by the window or dialog box. If no event processing is required, the keyword $NullHandler 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. Width is measured in character cells.
height The height (Y dimension) of the window excluding border, title bar, menu bar, toolbar, and status bar. Height is measured in character cells.
title The title displayed on the window title bar. The window must have a title bar for a title to be displayed.
style An integer bit mask that represents a list of style flags used to control the window's appearance.
For more information, see the Notes for this statement

Notes

WinCreateHyperViewer can be used to create a hypertext viewer. In addition to creating a window with the indicated position, size, and styles, WinCreateHyperViewer displays the contents of the indicated file. This file is assumed to contain ASCII text with embedded buttons. A button, which appears to the user as a highlighted word, is a link to another object such as a text file, sound file, picture, or program.

A button is defined in the following format:

[[<Button text> | <command>]]

<Button text> is the text to be displayed as highlighted text to the user, and <command> indicates the action that is initiated by the click.

Word Wrapping

The hypertext control expects the file provided to be formatted as a Tivoli Systems hypermedia file. This means that it word wraps all the lines of text (ignoring carriage returns) until it finds two carriage returns in a row.

Turning off Word Wrap and Formatting Defaults

To turn off word wrap and formatting defaults for a hypertext window, you can use aseview.exe to pass the /NOWORDWRAP /NOFORMAT flags in as command line arguments. This is the only way to programmatically turn off the word wrap and formatting defaults for a hypertext window.

WinCreateHyperviewer Command Options

The following table shows the command options for the WinCreateHyperViewer statement and descriptions:

Command Option Description
ID If the command is an integer, it is assumed to be a button ID. When the user clicks on the button, a $MsgButton message is sent to the hypertext viewer window's event handler. The button text is in event parameter one (string) and button ID is in event parameter two (integer).
If no command is provided (if the button is of the form [[Button-text]]), the event handler still receives a $MsgButton message when the button is selected. However, the button ID (event parameter two, integer) is 0. In this case, if the event handler returns zero, the viewer modifies the button text to have the formButtonTextand performs a search operation (see below).
JUMP JUMP <marker name> searches the tag list for a marker that matches the text following the Jump (see the Marker tag for more information). If a match is found, the line containing the marker is positioned at the top of the viewer and an EventJump is generated. The hypertext view processes the EventJump to keep a list of markers "visited" in a file.
LABEL LABEL <label-text> can be any character string. A $MsgLabel message is sent to the window's event handler with the button text in event parameter one (string) and the label text in event parameter two (string).
MARKER MARKER <marker name> places an invisible marker in the text.
SEARCH SEARCH <search-text> searches the current file starting at the top for <search-text>. The text may not cross lines unless the search text has embedded new lines. The search is case-sensitive except in Windows.
If the text is found, the viewer is positioned so the line containing the text appears on the top line of the viewer window.
FILE FILE <file-name> [NEW|REPLACE] [NOWORDWRAP|NOFORMAT] opens a new text file. By default, the new file replaces the one currently in the viewer. This is also the case if the keyword REPLACE follows <file-name>.
If the keyword NEW follows <file-name>, a new viewer window opens to display the new file.
The size of the viewer is determined by the system.
By default, word wrap is used so that all lines not separated by at least one empty line are treated as a flowed paragraph.
The first empty line after any non-empty line is discarded. The NOWORDWRAP keyword can be used to suppress this behavior. NOFORMAT used in conjunction with the default word wrapping, prevents adjacent lines from being combined but still wraps long lines.
IMAGE IMAGE <image-file>.BMP [SCROLL | SCALE]opens an image viewer and displays the indicated image file. By default, the image is clipped to fit the viewer size. The SCALE keyword causes the image to be scaled to the dimensions of the viewer. The SCROLL keyword clips the image but adds scroll bars to the viewer which can be used to scroll through the entire image.
PLAY PLAY <sound-file>.WAV plays the indicated audio file. A hypertext viewer window appears, which the user can manipulate to control the audio playback.
RUN RUN <app-name> executes the indicated application. <app-name> can be a string containing not only the name of an executable or command file but also command line arguments ([[Windows NT|RUN F:\DOC\DOCMAN.EXE WINDOWS_NT]]).


For a complete listing of the various types of messages that can be received by generic windows, see TSD Script Messages.

For a discussion of window style flags, see the WinCreate statement.

Example

KNOWLEDGEBASE WinHyper;
ROUTINES
 PROCEDURE HyperTextExample;
PRIVATE
CONSTANTS
 MENU_LIST {'File' ,'Open','/L ','Exit',''}: LIST OF STRING;
ROUTINES
 EVENT HyperTextEvent IS
 VARIABLES
 fileName: STRING;
 ACTIONS
 WHEN $Event IS $MsgCreate THEN
 WinSetMenuBar($Handle,MENU_LIST);
 WinSetIconBar($Handle,{'hyp_text.ico',
 'hypimage.ico',
 'hypsound.ico','search.ico'}:
LIST OF STRING);
 ELSWHEN $MsgMenu THEN
 WHEN $MenuSelection IS 1, 101 THEN
 IF WinFileDialog($Desktop,fileName,'*.*',
                  10,10, 'Select file to view',0)
                  < 0 THEN
                  WinMessageBox($Handle,'Error',
                  $MBOk+$MBIconError,fileName);
 ELSE
 SendMessage($Handle,$MsgOpenFile,fileName,
             fileName,0);
 END;
 ELSWHEN 2 THEN
 IF WinFileDialog($Desktop,fileName,'*.bmp',
                  10,10, 'Select bitmap to view',0)
                  < 0 THEN
 WinMessageBox( $Handle, 'Error', $MBOk+
               $MBIconError,fileName );
 ELSE
 SendMessage($Handle,$MsgDisplayImage,fileName,
             fileName,0);
 END;
 ELSWHEN 3 THEN
 IF WinFileDialog($Desktop,fileName,'*.wav',10,10,
                  'Select sound to play',0)
                  < 0 THEN
                  WinMessageBox($Handle,'Error',
                  $MBOk+$MBIconError,fileName);
 ELSE
 SendMessage($Handle,$MsgPlaySound,fileName,
             fileName,0);
 END;
 ELSWHEN 4 THEN
             IF WinEditField($Desktop,fileName,0,0,30,
             'Search for?',
             BitOr($WinAutoPos,
             $WinBorder,
             $WinTitle)) < 1 THEN
 WinMessageBox($Handle,'Error',
             $MBOk+$MBIconError,fileName);
 ELSE
 SendMessage($Handle,$MsgSearch,fileName);
 END;
 ELSWHEN 103 THEN
 SendMessage($Handle,$MsgClose);
 END;
 ELSWHEN $MsgChar THEN
 WHEN $KeyCode IS $KeyAltT THEN
 SendMessage($Handle,$MsgMenu,1);
 ELSWHEN $KeyAltI THEN
 SendMessage($Handle,$MsgMenu,2);
 ELSWHEN $KeyAltA THEN
 SendMessage($Handle,$MsgMenu,3);
 ELSWHEN $KeyAltS THEN
 SendMessage($Handle,$MsgMenu,4);
 ELSE
 WinMessageBox($Handle,'Hypertext Key',$MBOK,
 $KeyCode);
 END;
 ELSWHEN $MsgButton THEN
 WinMessageBox($Handle,'Hypertext Button',$MBOK,
               'Button text' &
               $EventParm(1,STRING) &
               'Button ID ' &
               $EventParm(2,INTEGER));
 ELSWHEN $MsgLabel THEN
 WinMessageBox($Handle,'Hypertext Button',$MBOK,
               'Button text ' &
               $EventParm(1,STRING) &
               'Button Label ' &
               $EventParm(2,STRING));
 END;
 END (* Hypertext Event *);
 PROCEDURE HyperTextExample IS
 VARIABLES
 whdl: WINDOW;
 ACTIONS
 WinCreateHyperViewer($Desktop,whdl,'formman.hlp',
                      HyperTextEvent,1,1,80,25,
                      'Hyertext Test',
                      BitOr($WinBorder,$WinTitle,
                      $WinResize,$WinMenu,
                      $WinIconBar,$WinSysMenu,
                      $WinMinMax,
                      $WinAutoPos,$WinAutoSize));
                      WinWait(whdl);
 END (* Hypertext Example *);

Return Codes

See Also

For more information about formatting hypermedia files, refer to the Tivoli Service Desk Developer's Toolkit Tools and Utilities Guide.

For more information on SAIPATH, see File Searching using SAIPATH.


WinCreateImage

Description

Creates a window that displays an image.

Syntax

FUNCTION WinCreateImage(VAL whdlParent: WINDOW,
 REF whdl: WINDOW,
 VAL fileName: STRING,
 VAL xLoc, yLoc, width, height:
 INTEGER,
 VAL title: STRING,
 VAL style, id: INTEGER): INTEGER;

Argument Notes

Argument Name Description
whdlParent Parent of the new window to be created.
whdl The handle of the newly created window is returned in this parameter. If there is an error, the variable is set to $Unknown.
fileName The file name of the displayed image. The image can be an OS/2 bitmap file, a Windows bitmap, or a .PCX image file.
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. Width is measured in character cells.
height The height (Y dimension) of the window excluding border, title bar, menu bar, toolbar, and status bar. Height is measured in character cells.
title The title displayed on the window title bar. The window must have a title bar for a title to be displayed. Use the $ImgTitle style.
style An integer bitmap that controls the behavior of the image window.
See the Notes section for information on style flag options.
id The ID (integer) used by the $MsgImage message to identify the image when reporting an event.

Notes

The image window style can be assembled from the following styles with the BITOR operator:

Style Description
$ImgScroll The image appears in the size it is in the file. The window has scroll bars. If the image is larger than the window, it may be scrolled.
$ImgClip The image appears in the size it is in the file. The top and right sides of the image are clipped to fit the window, if necessary.
$ImgScale The image scales in both width and height to fit the requested window size. The scaling process may distort the image.
$ImgBorder The image window has a border.
$ImgTitle The image window has a title. $ImgBorder must also be specified.
Image windows can respond to the $MsgSetImage message. This message, when accompanied by the name of an image file, causes the image window to load and display the indicated file.

Example

KNOWLEDGEBASE WinImage;
TYPES
 ImageRec IS RECORD
 fileName: STRING;
 whdlImage: WINDOW;
 END;
ROUTINES
 PROCEDURE ImageExample;
PRIVATE
ROUTINES
 EVENT ImageEvent(REF imageData: ImageRec) IS
 ACTIONS
 WHEN $Event IS $MsgCreate THEN
 WinSetMenuBar($Handle,{'File','Open','/L','Exit',''}:
               LIST OF STRING);
 WinCreateImage($Handle,imageData.whdlImage,
                'os2logo.bmp',1,1,WinWidth($Handle),
                WinHeight($Handle),'',$ImgScroll,1);
 ELSWHEN $MsgMenu THEN
 WHEN $MenuSelection IS 101 THEN
 IF WinFileDialog($Handle,imageData.fileName,'*.bmp',
                  10,10,'Select new image', 0 ) >= 1 THEN
 SendMessage(imageData.whdlImage,
             $MsgSetImage,imageData.fileName);
 END;
 ELSWHEN 103 THEN
 SendMessage($Handle,$MsgClose);
 END;
 ELSWHEN $MsgSize THEN
 SendMessage(imageData.whdlImage,$MsgSetSize,
             $EventParm(1,INTEGER),$EventParm(2,INTEGER));
 ELSWHEN $MsgImage THEN
 WinMessageBox($Handle,'Image',$MBOK,$EventParm(1,
               INTEGER));
 END;
 END (* Image Event *);
 PROCEDURE ImageExample IS
 VARIABLES
 whdl: WINDOW;
 data: ImageRec
 ACTIONS
 WinCreate($Desktop,whdl,ImageEvent{data},0,0,0,0,
           'Image test',
           BitOr($WinBorder,$WinTitle,$WinResize,
           $WinMenu,$WinMinMax,$WinTaskList,
           $WinSysMenu,$WinAutoPos,
           $WinAutoSize));
 WinWait(whdl);
 END (* Image Example *);

Return Codes

See Also


WinCreateMouseRect

Description

Creates a rectangular region that is sensitive to mouse clicks.

Syntax

FUNCTION WinCreateMouseRect(VAL whdl: WINDOW,
                            VAL xLoc, yLoc,
                            xLen, yLen, id: INTEGER):
 INTEGER;

Argument Notes

Argument Name Description
whdl Handle of the window where the rectangle is being created. The whdl argument can reference a standard window or a scroll window.
xLoc X-coordinate of upper left corner of the mouse zone.
yLoc Y-coordinate of upper left corner of the mouse zone.
xLen Width of mouse zone.
yLen Height of mouse zone.
id Integer used to identify the particular mouse zone.

Notes

By default, TSD Script does not report mouse events within a window. However, you can cause events such as mouse moves and clicks to be reported by creating a mouse zone. A mouse zone is a rectangular region within a window. When you create a mouse zone, you assign an integer ID to it. The ID is reported to the parent window along with all mouse events within that zone.

Whenever activity occurs within a mouse zone, the $MsgMouse message is sent to the parent of that zone along with the following four integer event parameters:

Tip: WinSetMousePointer must be called each time one of your windows processes a $MsgMouse event.

Example

KNOWLEDGEBASE WinMouse;
ROUTINES
 PROCEDURE MouseExample;
PRIVATE
CONSTANTS
 MENU_LIST IS {'File' ,
               'Exit','',
               'Pointer type',
               'MouseDefaultPtr',
               'MouseuLArrowPtr',
               'MouseURArrowPtr',
               'MouseDRArrowPtr',
               'MouseDLArrowPtr',
               'MouseUPResizePtr',
               'MouseURResizePtr',
               'MouseRTResizePtr',
               'MouseDRResizePtr',
               'MouseDNResizePtr',
               'MouseDLResizePtr',
               'MouseLTResizePtr',
               'MouseULResizePtr',
               'MouseCrossPtr',
               'MouseHandPtr',
               'MouseHourGlassPtr',
               'MouseIBeamPtr',''}: LIST OF STRING;
ROUTINES
 EVENT MouseEvent(REF pointerType: INTEGER) IS
 ROUTINES
 PROCEDURE ProcessMenu(VAL whdl: WINDOW, VAL selection:
 INTEGER) IS
 ACTIONS
 WHEN selection IS 101 THEN
 SendMessage(whdl,$MsgClose);
             ELSWHEN 201 THEN
 pointerType := $MouseDefaultPtr;
 ELSWHEN 202 THEN
 pointerType := $MouseuLArrowPtr;
 ELSWHEN 203 THEN
 pointerType := $MouseURArrowPtr;
 ELSWHEN 204 THEN
 pointerType := $MouseDRArrowPtr;
 ELSWHEN 205 THEN
 pointerType := $MouseDLArrowPtr;
 ELSWHEN 206 THEN
 pointerType := $MouseUPResizePtr;
 ELSWHEN 207 THEN
 pointerType := $MouseURResizePtr;
 ELSWHEN 208 THEN
 pointerType := $MouseRTResizePtr;
 ELSWHEN 209 THEN
 pointerType := $MouseDRResizePtr;
 ELSWHEN 210 THEN
 pointerType := $MouseDNResizePtr;
 ELSWHEN 211 THEN
 pointerType := $MouseDLResizePtr;
 ELSWHEN 212 THEN
 pointerType := $MouseLTResizePtr;
 ELSWHEN 213 THEN
 pointerType := $MouseULResizePtr;
 ELSWHEN 214 THEN
 pointerType := $MouseCrossPtr;
 ELSWHEN 215 THEN
 pointerType := $MouseHandPtr;
 ELSWHEN 216 THEN
 pointerType := $MouseHourGlassPtr;
 ELSWHEN 217 THEN
 pointerType := $MouseIBeamPtr;
 END;
 END (* Process Menu *);
 ACTIONS
 WHEN $Event IS $MsgCreate THEN
 WinSetMenuBar($Handle,MENU_LIST);
 ELSWHEN $MsgPaint THEN
 WinClear($Handle);
 WinCreateMouseRect($Handle,1,1,
                    WinWidth($Handle),
                    WinHeight($Handle),1);
 ELSWHEN $MsgMenu THEN
 ProcessMenu($Handle,$MenuSelection);
 ELSWHEN $MsgMouse THEN
 WinSetMousePointer($handle,pointerType);
 END;
 END (* Mouse Event *);
 PROCEDURE MouseExample IS
 VARIABLES
 whdlMain: WINDOW;
 ACTIONS
 WinCreate($Desktop,whdlMain,MouseEvent{
           $MouseDefaultPtr},
           0,0,60,20,
           'Mouse example',
           BitOr($WinBorder,$WinTitle,
           $WinResize,$WinMenu,
           $WinVScroll,$WinMinMax,
           $WinTaskList,
           $WinSysMenu,$WinAutoPos));
 WinWait(whdlMain);
 END (* Mouse Example *);

Return Codes

See Also

For more information, see Mouse Pointers and Mouse Messages.


WinCreateScrollWindow

Description

Creates a modeless, scroll window that automatically repaints itself as necessary.

Syntax

WinCreateScrollWindow(VAL whdlParent: WINDOW,
                      REF whdl: WINDOW,|
                      VAL EventHandler: EVENT,
                      VAL xLoc, yLoc, width, height: INTEGER,
                      VAL title, font: STRING,
                      VAL pointSize, style: INTEGER):
                      INTEGER;

Argument Notes

Argument Name Description
whdlParent Parent of the scroll 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 $NullHandler can be used.
xLoc The X location of the upper left corner of the window. X and Y coordinates are measured in character cells.
yLoc The Y location of the upper left corner of the window.
width The width (X dimension) of the window excluding the border. Width is measured in character cells.
height The height (Y dimension) of the window excluding the border, title bar, menu bar, toolbar, and status bar. Height is measured in character cells.
title The title displayed on the window title bar. The window must have a title bar in order 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.
See the Notes section for the WinCreate statement for more information.

Notes

First Messages Received

When a scroll window is created, the following messages are received in the order shown:

Tracking and Repainting Scroll Windows

WinCreateScrollWindow can be used to create a virtual scrolling window. In generic windows, the programmer is responsible for knowing the window's contents and redisplaying the window on receipt of a $MsgPaint message. Scroll windows "know" their contents. Programmers write information into them by means of WinWrite, WinWriteLN, and so on.

Note: For a list of the messages that scroll windows can generate and receive, see TSD Script Messages.

Customizing Scroll Windows

Scroll windows can contain toolbars, menu bars, status bars, and all the other window elements available to generic windows.

Example

KNOWLEDGEBASE Scroll;
CONSTANTS
 MENU_OPEN IS 101;
 MENU_EXIT IS 102;

 MENU_LIST IS {'~File','~Open','E~xit',''}:
 LIST OF STRING;
TYPES
 EditorData IS RECORD
 statusLine: STRING;
 lines: LIST OF STRING;
 END;
ROUTINES
 PROCEDURE FileView;
PRIVATE
ROUTINES
 EVENT EditorEvent(REF editorData: EditorData) IS
 ROUTINES
 PROCEDURE ProcessMainMenu(VALUE selection: INTEGER) IS
 VARIABLES
 fileName: STRING;
 editFile: FILE;
 result: INTEGER;
 ACTIONS
 WHEN selection IS MENU_OPEN THEN
 WinFileDialog($Handle,fileName,'*.KB',5,5,
               'Select file to edit',0);
 IF FOpen(editFile,fileName,$Read) > 0 THEN
 FReadText(editFile,editorData.lines);
 FClose(editFile);
 editorData.statusLine := ' File: ' & fileName;
 WinClear($Handle);
 WinWriteLN($Handle,editorData.lines);
 PostMessage($Handle,$MsgPaintStatus);
 ELSWHEN MENU_EXIT THEN
 SendMessage($Handle,$MsgClose);
 END;
 END;
 END (* Process Main Menu *);
 ACTIONS
 WHEN $Event IS $MsgCreate THEN
 WinSetMenuBar($Handle, menuList);
 editorData.statusLine := 'File:';
 ELSWHEN $MsgMenu THEN
 ProcessMainMenu($MenuSelection);
 ELSWHEN $MsgPaintStatus THEN (* Status Bar *)
 WinClear($Handle);
 WinWrite($Handle,editorData.statusLine);
 END;
 END (* Editor Event *);
 PROCEDURE FileView IS
 VARIABLES
 whdl: WINDOW;
 ACTIONS
 WinCreateScrollWindow($Desktop,whdl,EditorEvent,
                       0,0,0,0,
                       'KML File viewer',
                       $SystemMonospaced,10,
                       BitOr($WinBorder,$WinTitle,
                       $WinResize, $WinSysMenu,
                       $WinMenu,$WinStatus,
                       $WinAutoPos,$WinAutoSize,
                       $WinVScroll,$WinHScroll,
                       $WinTaskList));
 WinWait(whdl);
 END (* File View *);

Return Codes

See Also

For more information, see Window Styles.


WinEditField

Description

Displays a one-line editor for the data type of the edit value.

Syntax

FUNCTION WinEditField(VAL parent: WINDOW, REF value: ANY,
 VAL xLoc, yLoc, length: INTEGER, title:
 STRING,
 VAL style: INTEGER):
 INTEGER;

Argument Notes

Argument Name Description
parent Parent of the new window to be created. In Windows, if the parent window is disabled when WinEditField is called, the WinEditField window does not clip to the parent window.
In Windows, if $Desktop is specified as the parent in combination with $WinModal, the window created with WinEditField is modeless.
The following section describes the style flags, such as $WinModal.
xLoc The X location of the upper left corner of the window.
yLoc The Y location of the upper left corner of the window.
length The width (X dimension) of the window excluding border.
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. In Windows, the $WinTitle constant is added automatically if you do not specify it.
style An integer containing a list of style flags controlling the window's appearance. See the following section on the available style flags for details.

Notes

The available style flags for WinEditField are listed in the table.

Style Flag Description
$WinAutoPos The system determines the best position for the window. The xLoc and yLoc parameters are ignored.
$WinAutoSize The system determines the best size for the window. The xLen and yLen parameters are ignored.
$WinBorder The window has a border similar to a dialog box. Several styles require a border. In Windows, the $WinBorder constant is added automatically if you do not specify it.
$WinDefaultStyle A system-defined default style assembled from $WinBorder, $WinResize, $WinTitle, and $WinSysMenu.
$WinField The window has a single-pixel border (like controls in dialog boxes). This style is mutually exclusive with $WinBorder.
$WinInvisible The window is created hidden. It must be sent a $MsgShow to become visible.
$WinModal When the edit field is created, it is a modal window. The parent of the edit field window and all of the other child windows is disabled.
$WinNone The window is bare with no border, title bar, or other elements.
$WinTaskList The window title is entered into the system task list. The user may activate the window from the task list. This style should generally be used for the main window of an application.
$WinTitle The window has a title bar. If this style is not present, no title is displayed even if a title is specified as one of the parameters. A title bar makes the window movable.

Example

VARIABLES
 intVal: INTEGER;
ACTIONS
 WinEditField($Desktop,intVal,0,0,30,'Integer',
              $WinAutoPos+$WinBorder+
              $WinTitle);

Return Codes

See Also

DlgBox


WinEnableWindow

Description

Enables or disables a dialog box or a window.

Syntax

FUNCTION WinEnableWindow(VAL whdl: WINDOW, VAL state:
                         BOOLEAN): INTEGER;

Argument Notes

Argument Name Description
whdl Handle of the dialog box or window whose enabled state is to be changed.
state Set to TRUE if the window is to be "enabled", set to FALSE if it is to be "disabled."

Notes

This function is also implemented as a message that can be passed to a dialog box form or window ($MsgEnable).

Example

KNOWLEDGEBASE enable;
ROUTINES
 PROCEDURE Main;
PRIVATE
ROUTINES
 PROCEDURE Main IS
 VARIABLES
 Handle : WINDOW;
 ACTIONS
 WinCreate($Desktop,
           Handle,
           $NullHandler,
           1, 1,
           80, 25,
           'Test Window',
           $WinDefaultStyle);
 WinEnableWindow(Handle, FALSE);
 SysDelay(1000);
 WinEnableWindow(HANDLE, TRUE);
 WinWait(Handle);
END;

Return Codes


WinFileDialog

Description

Displays a file selection dialog box.

Syntax

FUNCTION WinFileDialog(VAL whdlParent: WINDOW,
                       REF fileName: STRING,
                       VAL startMask: STRING,
                       VAL xLoc, yLoc: INTEGER,
                       VAL title: STRING, VAL style: INTEGER
                       ): INTEGER;

Argument Notes

Argument Name Description
whdlParent Parent of the new window to be created.
fileName Returns the file name selected by the user. If the user cancels the dialog box, the value is unchanged.
startMask The initial file selection mask, *, and ? wildcard characters may be used.
xLoc The X location of the lower left corner of the window.
yLoc The Y location of the lower left corner of the window.
title The title displayed on the window title bar. The window must have a title bar for a title to be displayed. Use the $WinTitle style.
style The style of the file dialog box. Possible values are:
  • $FileDlgCenter - Centers file dialog box on screen.
  • $FileDlgOpen - Creates a File Open dialog box.
  • $FileDlgSaveAs - Creates a Save As dialog box. Names of existing file are displayed as inactive.

Notes

You can use WinFileDialog whenever you want to prompt users for a file name, either when opening a new file or allowing them to save work to a new file. By setting the startMask argument, you can use WinFileDialog to choose specific types of files (for example, use *.kb for knowledgebases).

Tip: The xLoc and yLoc parameters have no effect in Windows.

Example

VARIABLES
 fileName: STRING;
ACTIONS
 IF WinFileDialog($Desktop,fileName,'*.TXT',
 10,10, 'Select file to edit',0) > 0 THEN
 LoadAndEdit(fileName);
 END;

Return Codes

See Also


WinGetXPos

Description

Queries the X coordinate position of any valid window handle (window or a dialog box). Position 00 is the top-left corner.

Syntax

FUNCTION WinGetXPos (VAL whdl: Window): Integer;

Argument Notes

Argument Name Description
whdl Window handle to query X position

Notes

WinGetXPos differs from WinX because it queries the top-left corner of the window or dialog box, while WinX returns a character position within a window. The X coordinate position returns on success.

Example

KNOWLEDGEBASE GetPos;
ROUTINES
 PROCEDURE Main;
PRIVATE
ROUTINES
 PROCEDURE Main IS
 VARIABLES
 Handle : WINDOW;
 x,y : INTEGER;
 ACTIONS
 WinCreateScrollWindow($Desktop,
                       Handle,
                       $Nullhandler,
                       10,10,75,25,
                       'Test',
                       $SystemMonospaced,10,
                       $WinDefaultStyle);
                       x := WinGetXPos(Handle);
 y := WinGetYPos(Handle);
 WinWriteLN(Handle, 'The upper left corner
            of the window is at
            (' & x & ', ' & y & ')');
 WinWait(Handle);
 END;

Return Codes

See Also

WinGetYPos


WinGetYPos

Description

Queries the Y coordinate position of any valid window handle (either a window or a dialog box). Position 00 is the top left corner of the window or dialog box.

Syntax

FUNCTION WinGetYPos (VAL whdl: Window): Integer;

Argument Notes

Argument Name Description
whdl Window handle to query Y position

Notes

WinGetYPos differs from WinY because it queries the top left corner of a window or dialog box, while WinY returns a character position within a window.

Example

See the example for the WinGetXPos statement.

Return Codes

See Also

WinGetXPos


WinGoToXY

Description

Moves the position pointer to a new location.

Syntax

FUNCTION WinGoToXY(VAL whdl: WINDOW, VAL xLoc, yLoc:
 INTEGER): INTEGER;

Argument Notes

Argument Name Description
whdl The handle of the window on which the operation is to be performed
xLoc New X location of current position pointer
yLoc New Y location of current position pointer

Example

WHEN $Event IS $MsgChar THEN
 WHEN $EventParm(1,INTEGER) IS $KeyUpArrow THEN
                 WinGoToXY(Handle,$WinX($Handle),$WinY($Handle)-1);
 ELSWHEN $KeyRightArrow THEN
 WinGoToXY(Handle,$WinX($Handle)+1,$WinY($Handle));
 END;
END;

Return Codes

See Also


WinHeight

Description

Queries the height of a window and returns the height, expressed in character cells.

Syntax

FUNCTION WinHeight(VAL whdl: WINDOW): INTEGER;

Argument Notes

Argument Name Description
whdl The handle of the window on which the operation is to be performed.

Notes

WinHeight returns the current client area height of a given window.

Example

WinCreateMouseZone($Handle,1,1,
                   WinWidth($Handle),WinHeight($Handle),1);

Return Codes

See Also


WinLoadMenuBar

Description

Loads a menu from a resource file and attaches it to a specific window. (Any previously attached menu is replaced.)

Syntax

FUNCTION WinLoadMenuBar(VAL win: WINDOW,
                        VAL resource : STRING
                        ) : INTEGER;

Argument Notes

Argument Name Description
win Form, generic, scroll, or hypertext
resource Resource string in standard format

Notes

A short cut for attaching a menu to a form is to give the menu the same name as the form within the same .df file. The menu is loaded automatically if the form has the menu style.

Example

KNOWLEDGEBASE loadmenu;
ROUTINES
PROCEDURE Main;
(* ***** PRIVATE ***** *)
PRIVATE
VARIABLES
 (* Global Variable to hold the Window handle of the window *)
 mainWindow : WINDOW;
ROUTINES
PROCEDURE Main IS
VARIABLES
ACTIONS
 WinCreate($Desktop, mainWindow, $NullHandler, 10, 10, 80, 25, 'Test Window', $WinDefaultStyle);
 (*load the menu with id MAIN_MENU from the file loadmenu.df *)
 WinLoadMenuBar(mainWindow, 'loadmenu[MAIN_MENU]');
 WinWait(mainWindow);
END;

Return Codes

See Also


WinLoadPopupMenu

Description

Loads a menu resource from a .df file and associates it as the pop-up menu for the window, replacing any existing pop-up menu. The pop-up menu automatically appears and uses the correct mouse action for the platform. Selections from the pop-up menu are reported by $MsgMenu.

Syntax

FUNCTION WinLoadPopupMenu( VAL whdl: WINDOW,
                          VAL menu: STRING,
                          ) : INTEGER;

Argument Notes

Argument Name Description
whdl The handle of the dialog box form or window whose title text is to be changed
menu The fully qualified name of the specification file describing the menu to the created menu

Notes

When using WinLoadPopupMenu, the menu automatically appears upon the correct mouse action for the platform. When the user selects a menu item, a $MsgMenu is sent to the window. This differs from the old function WinPopup. In WinPopup, the user would have to catch the correct mouse action and call WinPopup to display the pop-up menu. WinPopup would return the id of the menu item selected.

Example

KNOWLEDGEBASE loadpop;
ROUTINES
PROCEDURE Main;
(* ***** PRIVATE ***** *)
PRIVATE
VARIABLES
 (* Global Variable to hold the Window handle of the window *)
 mainWindow : WINDOW;
ROUTINES
PROCEDURE Main IS
VARIABLES
ACTIONS
 WinCreate($Desktop, mainWindow, $NullHandler, 10, 10, 80, 25, 'Test Window', $WinDefaultStyle);
 (* load the menu with id MAIN_MENU from the file loadmenu.df *)
 WinLoadPopupMenu(mainWindow, 'loadmenu[MAIN_MENU]');
 WinWait(mainWindow);
END;

Return Codes

See Also

WinSetPopupMenu


WinLoadToolBar

Description

Loads a toolbar from a resource file and attaches it to a specific window. (Any previously attached toolbar is replaced.)

Syntax

FUNCTION WinLoadToolBar(VAL win: WINDOW,
 VAL resource : STRING
 ): INTEGER;

Argument Notes

Argument Name Description
win Form, generic, scroll, or hypertext
resource Resource string in standard format

Notes

A short cut to attach a toolbar to a form is to specify a toolbar with the same name as the form within the same .df file. The toolbar is loaded automatically if the form has the toolbar style.

Example

KNOWLEDGEBASE loadtool;
ROUTINES
PROCEDURE Main;
(* ***** PRIVATE ***** *)
PRIVATE
VARIABLES
 (* Global Variable to hold the Window handle of the window *)
 mainWindow : WINDOW;
ROUTINES
PROCEDURE Main IS
VARIABLES
ACTIONS
 WinCreate($Desktop, mainWindow, $NullHandler, 10, 10, 80, 25, 'Test Window', $WinDefaultStyle);
 (* load the toolbar with id MAIN_TOOLBAR from the file loadtool.df *)
 WinLoadToolBar(mainWindow, 'loadtool[MAIN_TOOLBAR]');
 WinWait(mainWindow);
END;

Return Codes

See Also


WinMenuCheckItem

Description

Sets the checked state of a menu item.

Syntax

FUNCTION WinMenuCheckItem(VAL whdl: WINDOW,
                          VAL id: STRING,
                          VAL newState: BOOLEAN): INTEGER;
FUNCTION WinMenuCheckItem(VAL whdl: WINDOW,
                          VAL id: INTEGER,
                          VAL newState: BOOLEAN): INTEGER;

Argument Notes

Argument Name Description
whdl Handle of a window that has a menu bar
id The ID of the menu item to be set
newState The new state of the menu item

Notes

WinMenuCheckItem allows you to check and uncheck a menu item. The current checked status of a given option can be tested when you call WinMenuItemIsChecked.

Note: Menu items can be identified with strings or integers.

Example

WinMenuCheckItem($Handle,204,TRUE);

Return Codes

See Also


WinMenuEnableItem

Description

Sets the enabled or disabled state of a menu item.

Syntax

FUNCTION WinMenuEnableItem(VAL whdl: WINDOW,
                           VAL id: STRING,
                           VAL newState: BOOLEAN): INTEGER;
FUNCTION WinMenuEnableItem(VAL whdl: WINDOW,
                           VAL id: INTEGER,
                           VAL newState: BOOLEAN): INTEGER;

Argument Notes

Argument Name Description
whdl Handle of a window that has a menu bar
id The ID of the menu item to be set
newState The new state of the menu item

Notes

WinMenuEnableItem can be used to enable or disable a menu item. Disabled items are unavailable. The $SysMenuCloseItem constant can be used to enable or disable the Close item on a window's system menu in the following way:

(* This line enables the Close item *)
WinMenuEnableItem (myWindow, $SysMenuCloseItem, TRUE);
(* This line disables the Close item *)
WinMenuEnableItem (myWindow, $SysMenuCloseItem, FALSE);

Note: Menu items can be identified with strings or integers.

Example

WinMenuEnableItem($Handle,204,TRUE);

Return Codes

See Also


WinMenuItemIsChecked

Description

Tests to see whether a menu item is currently checked.

Syntax

FUNCTION WinMenuItemIsChecked(VAL whdl: WINDOW,
                              VAL id: STRING): BOOLEAN;
FUNCTION WinMenuItemIsChecked(VAL whdl: WINDOW,
                              VAL id: INTEGER): BOOLEAN;

Argument Notes

Argument Name Description
whdl Handle of a window that has a menu bar
id The ID of the menu item to be set

Notes

TSD Script allows you to set up a menu bar of selection items. You can check a given menu item to see if it is selected by calling WinMenuItemIsChecked and passing two items:

Note: Menu items can be identified with strings or integers.

Example

IF WinMenuItemIsChecked($Handle,204) THEN
 CarryOutAction;
END;

Return Codes

See Also


WinMessageBox

Description

Displays a message box and returns a user selection. (Message text is limited to 512 characters.)

Syntax

FUNCTION WinMessageBox(VAL whdlParent: WINDOW,
                       VAL title: STRING,
                       VAL style: INTEGER,
                       VAL message: STRING): INTEGER;

Cautions

Event Handlers and DDE

Do not use WinWait when you process a $MsgDDEInitiate message. $MsgDDEInitiate broadcasts a message to the applications and locks the message queue until a response is returned. Meanwhile, the WinWait statement initiates an event handler that also waits for a reply from the message queue. WinWait prevents the other applications from sending messages to the message queue. This results in a deadlock, and effectively locks the user interface.

Argument Notes

Argument Name Description
whdlParent The parent of the message box. If this is $Desktop, the message box cannot be modal.
title The title displayed on the window title bar. The window must have a title bar in order for a title to be displayed. Use the $WinTitle style.
style The style of the message box. This is a bit mask that controls the appearance and behavior of the message box.
See the Notes section for an explanation of the style options.
messageText Text of message to display. Word wrap and new line are supported. (Limited to 512 characters.)

Notes

Description of a Message Box

A message box is a simple dialog box that you create with WinMessageBox. It is not necessary to create a .df file or use the Interface Designer.

When using WinMessageBox, you can add only a title, a text string (the message), and up to three buttons. You cannot add other text boxes or controls.

Customizing Message Boxes

The style of a message box is a combination of the following settings:

Style Name Description
Button style Indicates the button choices that appear within the message box.
Icon style Indicates a type of icon to be displayed within the message box.
Default button Indicates which of the buttons is to be the default.
Mode Indicates the modality of the message box. This determines whether the user can do anything else before responding to the message box.
Title In OS/2, if you want to add a title bar to your window, you must specify the $WinTitle constant. In Windows, all windows automatically have a title bar.

To create the style of a message box choose one of the following button styles:

Choose zero or more of the following icon styles:

Choose zero or one of the following default buttons:

Choose zero or one of the following modes:

If the message box has a Cancel button, the Esc key closes the message box and WinMessageBox returns $MBResultCancel. If there is not a Cancel button, the Esc key has no effect. $MBResultError is returned only in the case of an internal error condition.

The message box automatically sizes itself, based on the message text and title length. The message box may be up to two-thirds the height of the screen.

Example

WinMessageBox ($Desktop,'Error',$MBOK+$MBIconError,
               'Unable to open file');

Return Codes

See Also

For a list of the style flags, see Message Box Styles.


WinParent

Description

Parent of the window that was passed as its argument.

Syntax

FUNCTION WinParent(VAL whdl: WINDOW): WINDOW;

Argument Notes

Argument Name Description
whdl The handle of the window whose parent is requested

Example

VARIABLES
 parent: WINDOW;
ACTIONS
 parent := WinParent($Handle);

Return Codes

Returns the parent of the window that was passed as its argument.

See Also


WinSetColor

Description

Sets the current drawing colors of a window. The drawing colors determine the color of the text and the color of the background.

Syntax

FUNCTION WinSetColor(VAL whdl: WINDOW, VAL foreGround:
                     INTEGER; VAL backGround: INTEGER):
                     INTEGER;

Argument Notes

Argument Name Description
whdl The handle of the window on which the operation is to be performed.
foreGround The new foreground drawing color. See the Notes section for a complete list of the color constants.
backGround The new background drawing color. See the Notes section for a complete list of the color constants.

Notes

Predefined Color Constants

The following predefined color constants are available for use:

Note: $WinDefaultColor selects the system default foreground or background for the window.

$WinTransparent causes all text output operations to write transparent text until a call to WinSetColor with $WinOpaque as the background color. Transparent text is the default.

$WinOpaque causes all text output operations to write opaque text. That is, a rectangle surrounding the text is cleared to the current background color. $WinOpaque remains in effect until a call to WinSetColor with $WinTransparent as the background color.

Accessing Operating System-defined Colors

Use the following predefined constants to access user-configurable colors defined by the operating system:

Example

WHEN $Event IS $MsgPaint THEN
 WinSetColor($Handle,$WinWhite,$WinBlack);
 WinClear($Handle);
END;

Return Codes

See Also


Tivoli Service Desk 6.0 Developer's Toolkit Script Language Reference

Return to Main Page

Copyright