Blitz:Windows

From AmigaBlitzWiki
Jump to: navigation, search

Windows are the basis for the standard user interface. They provide your program with its own area of the screen which can be manipulated in the same way all the other windows, and can contain all the elements your program requires for user interaction. Multiple windows can be opened at any time by a program, and they can be opened on any public screen or your own private screen.

Opening Windows

Like screens, windows are opened by a single command that assigns an ID number and provides all the parameters required. This is (unsurprisingly) the Window command. This command is used as follows:

Window  Window#, X, Y, Width, Height, Flags, Title$, Dpen, Bpen [,GadgetList#]

Where Window# is the ID number you assign, and must be unique within your program. X and Y are the coordinates on screen of the top left corner of the window. Width and Height are the width and height of your entire window in pixels, including the border. Flags are special values used to set certain properties of the window. Title$ is a string containing the title to be displayed in the title bar of the window. Dpen and Bpen are the detail and block pens and are usually 0 and 1 respectively, however they are only used under OS 1.x. The optional GadgetList# is the ID number of an Intuition GadgetList object containing gadgets to display in the window.

An example is as follows:

Window 0, 100, 100, 200, 100, #WFLG_DRAGBAR|#WFLG_DEPTHGADGET|#WFLG_CLOSEGADGET|#WFLG_ACTIVATE, "Test Window", 1, 2

This will open a 200x100 pixel window positioned at 100x100 on the currently used screen with the title "Test Window". The flags supplied set the particular attributes, in this case our window will have a drag bar, depth gadget, close gadget, and will be activated as soon as it opens.

Note: in AmiBlitz, the Window statement can also be used as a function in order to determine if the window was opened successfully, in which case the parameters must be put in brackets, and the return value is a long word. It's good practice to check for success whenever you can so that you can deal with the failure gracefully instead of crashing! For example:

win.l = Window(0, 100, 100, 200, 100, #WFLG_DRAGBAR|#WFLG_DEPTHGADGET|#WFLG_CLOSEGADGET|#WFLG_ACTIVATE, "Test Window", 1, 2)
If win = False Then NPrint "Unable to open window!":End

Blitz Basic documentation and examples generally use the values that the flags represent directly, which is fine although it can make it harder to read later on. The flag values are listed in the official Amiga autodocs, and in the Blitz Basic manual. The file amigalibs.res needs to be resident in order to have these constants already defined.

Controlling Windows

Windows can be controlled using various other commands built into Blitz:

CloseWindow window#
Closes the specified window. Note: If you use GadTools Menus, you must close your window before you End the program!
WMove X, Y
Moves the window to the coordinates specified
WSize Width, Height
Resizes window to the specified size
Activate Window window#
Sets the specified window as active, as if the user had clicked on it
WTitle windowtitle$ [,screentitle$]
Sets the current window's title, and optionally the parent screen's title as well which will be shown when the window is active. Note: Setting the screen title in this way does not work under OS4. Instead it must be set directly in the window's structure. Setting the screen and window titles in the structure will work on all versions of the OS.


Other commands are available for more advanced control regarding event handling, text input and output, graphics commands, using fonts other than the default screen font, scrolling and so on. See the Window Commands section of the Blitz manual for details.

Bear in mind that some GUI toolkits (e.g. MUI) handle the window themselves, which means you don't need to worry about setting up your program's windows in this way. Windows are the basis for the standard user interface. They provide your program with its own area of the screen which can be manipulated in the same way all the other windows, and can contain all the elements your program requires for user interaction. Multiple windows can be opened at any time by a program, and they can be opened on any public screen or your own private screen.

Opening Windows

Like screens, windows are opened by a single command that assigns an ID number and provides all the parameters required. This is (unsurprisingly) the Window command. This command is used as follows:

Window  Window#, X, Y, Width, Height, Flags, Title$, Dpen, Bpen [,GadgetList#]

Where Window# is the ID number you assign, and must be unique within your program. X and Y are the coordinates on screen of the top left corner of the window. Width and Height are the width and height of your entire window in pixels, including the border. Flags are special values used to set certain properties of the window. Title$ is a string containing the title to be displayed in the title bar of the window. Dpen and Bpen are the detail and block pens and are usually 0 and 1 respectively, however they are only used under OS 1.x. The optional GadgetList# is the ID number of an Intuition GadgetList object containing gadgets to display in the window.

An example is as follows:

Window 0, 100, 100, 200, 100, #WFLG_DRAGBAR|#WFLG_DEPTHGADGET|#WFLG_CLOSEGADGET|#WFLG_ACTIVATE, "Test Window", 1, 2

This will open a 200x100 pixel window positioned at 100x100 on the currently used screen with the title "Test Window". The flags supplied set the particular attributes, in this case our window will have a drag bar, depth gadget, close gadget, and will be activated as soon as it opens.

Note: in AmiBlitz, the Window statement can also be used as a function in order to determine if the window was opened successfully, in which case the parameters must be put in brackets, and the return value is a long word. It's good practice to check for success whenever you can so that you can deal with the failure gracefully instead of crashing! For example:

win.l = Window(0, 100, 100, 200, 100, #WFLG_DRAGBAR|#WFLG_DEPTHGADGET|#WFLG_CLOSEGADGET|#WFLG_ACTIVATE, "Test Window", 1, 2)
If win = False Then NPrint "Unable to open window!":End

Blitz Basic documentation and examples generally use the values that the flags represent directly, which is fine although it can make it harder to read later on. The flag values are listed in the official Amiga autodocs, and in the Blitz Basic manual. The file amigalibs.res needs to be resident in order to have these constants already defined.

Controlling Windows

Windows can be controlled using various other commands built into Blitz:

CloseWindow window#
Closes the specified window. Note: If you use GadTools Menus, you must close your window before you End the program!
WMove X, Y
Moves the window to the coordinates specified
WSize Width, Height
Resizes window to the specified size
Activate Window window#
Sets the specified window as active, as if the user had clicked on it
WTitle windowtitle$ [,screentitle$]
Sets the current window's title, and optionally the parent screen's title as well which will be shown when the window is active. Note: Setting the screen title in this way does not work under OS4. Instead it must be set directly in the window's structure. Setting the screen and window titles in the structure will work on all versions of the OS.


Other commands are available for more advanced control regarding event handling, text input and output, graphics commands, using fonts other than the default screen font, scrolling and so on. See the Window Commands section of the Blitz manual for details.

Bear in mind that some GUI toolkits (e.g. MUI) handle the window themselves, which means you don't need to worry about setting up your program's windows in this way.