R-23: WINDOW COMMANDS
Windows are the heart of the user friendly Amiga operating system. Not only are they
the graphics device used for both user input and display but are the heart of the
messaging system that communicates this information to your program by way of the
Typically a Blitz program will either open or find a screen to use, define a list of
gadgets and then open a window on the screen with the gadget list attached. It will
then wait for an event such as the user selecting a menu or hitting a gadget and act
The program can specify which events they wish to receive by modifying the IDCMP
flags for the window. Once an event is received Blitz has a wide range of commands
for finding out exactly what the user has gone and done.
Blitz also offers a number of drawing commands that allow the programmer to render
graphics to the currently used window.
Window opens an Intuition window on the currently used screen. Window# is a unique
object number for the new window. X and Y refer to the offset from the top left of
the screen the window is to appear at. Width and Height are the size of the window
Flags are the special window flags that a window can have when opened. These flags
allow for the inclusion of a sizing gadget, dragbar and many other things. The flags
are listed as followed, with their corresponding values. To select more than one of
these flags, they must be logically Or'd together using the 'l' operator.
For example, to open a window with dragbar and sizing gadget which is active once
opened, you would specify a Flags parameter of $1 $21 $1000.
Title$ is a BASIC string, either a constant or a variable, that you want to be the
title of the window.
Dpen is the colour of the detail pen of the window. This colour is used for the
BPen is the block pen of the window. This pen is used for things like the border
around the edge of the window.
The optional GadgetList# is the number of a gadgetlist object you have may want
attached to the window.
After the window has opened, it will become the currently used window.
The Window library has been extended to handle super bitmap windows. SuperBitMap
windows allow the window to have it's own bitmap which can actually be larger than
the window. The two main benefits of this feature are the window's ability to
refresh itself and the ability to scroll around a large area "inside" the bitmap.
To attach a BitMap to a Window set the SuperBitMap flag in the flags field and
include the BitMap# to be attached.
Window Flag Value Description
WINDOWSIZING $0001 Attaches sizing gadget to bottom right corner of window and allows
it to be sized.
WINDOWDRAG $0002 Allows window to be dragged with the mouse by it's title bar.
WINDOWDEPTH $0004 Lets windows be pushed behind or pulled in front of other windows.
WINDOWCLOSE $0008 Attaches a closegadget to the upper left corner of the window.
SIZEBRIGHT $0010 With GIMMEZEROZERO and WINDOWSIZING set, this will leave the right
hand margin, the width of the sizing gadget, clear, and any drawing
to the window will not extend over this right margin.
SIZEBBOTTOM $0020 Same as SIZEBRIGHT except it leaves a margin at the bottom of the
window, the width of the sizing gadget.
BACKDROP $0100 This opens the window behind any other window that is already
opened. It cannot have the WINDOWDEPTH flag set also, as the
window is intended to stay behind all others.
GIMME00 $0400 This flag keeps the windows border separate from the rest of the
windows area. Any drawing on the window, extending to the borders,
will not overwrite the border.
NOTE: Although convevient, this does take up more memory than usual.
BORDERLESS $0800 Opens a window without any border on it at all.
ACTIVATE $1000 Activates the window once opened.
Use Window Window#
Use Window will cause the specified window object to become the currently used
window. Use Window also automatically performs a WindowInput and WindowOutput on the
Free Window Window#
Free Window closes down a window. This window is now gone, and can not be accessed
any more by any statements or functions. Once a window is closed, you may want to
direct the input and output somewhere new, by calling Use Window on another window,
DefaultOutput/DefaultInput, or by some other appropriate means. Window# is the
window object number to close.
Windowinput will cause any future executions of the Inkey$, Edit$ or Edit functions
to receive their input as keystrokes from the specified window object.
WindowInput is automatically executed when either a window is opened, or Use Window
After a window is closed (using Free Window), remember to tell Blitz to get it's
input from somewhere else useful (for example, using another WindowInput command)
before executing another Inkey$, Edit$ or Edit function.
WindowOutput will cause any future executions of either the Print or NPrint
statements to send their output as text to the specified window object.
WindowOutput is automatically executed when either a window is opened, or Use Window
After a window is closed (using Free Window), remember to send output somewhere else
useful (for example, using another WindowOutput command) before executing another
Print or NPrint statement.
DefaultIDCMP allows you to set the IDCMP flags used when opening further windows.
You can change the flags as often as you like, causing all of your windows to have
their own set of IDCMP flags if you wish.
A window's IDCMP flags will affect the types of 'events' reportable by the window.
Events are reported to a program by means of either the WaitEvent or Event
To select more than one IDCMP Flag when using DefaultIDCMP, combine the separate
flags together using the OR operator ('|').
Any windows opened before any DefaultIDCMP command is executed will be opened using
an IDCMP flags setting of:
$21 $41 $81 $201 $401 $1001 $2001 $4001 $400001 $80000.
This should be sufficient for most programs.
If you do use DefaultIDCMP for some reason, it is important to remember to include
all flags necessary for the functioning of the program. For example, if you open a
window which is to have menus attached to it, you MUST set the $100 (menu selected)
IDCMP flag, or else you will have no way of telling when a menu has been selected.
$2 Reported when a window has it's size changed.
$4 Reported when a windows contents have been corrupted.
This may mean a windows contents may need to be re-drawn.
$8 Reported when either mouse button has been hit.
$10 Reported when the mouse has been moved.
$20 Reported when a gadget within a window has been pushed 'down'.
$40 Reported when a gadget within a window has been 'released'.
$100 Reported when a menu operation within a window has occured.
$200 Reported when the 'close' gadget of a window has been selected.
$400 Reported when a keypress has been detected.
$8000 Reported when a disk is inserted into a disk drive.
$10000 Reported when a disk is removed from a disk drive.
$40000 Reported when a window has been 'activated'.
$80000 Reported when a window has been 'de-activated'.
AddIDCMP allows you to 'add in' IDCMP flags to the IDCMP flags selected by
DefaultIDCMP. Please refer to DefaultIDCMP for a thorough discussion of IDCMP flags.
SubIDCMP allows you to 'subtract out' IDCMP flags from the IDCMP flags selected by
DefaultIDCMP. Please refer to DefaultIDCMP for a thorough discussion of IDCMP flags.
WaitEvent will halt program excution until an Intuition event has been received.
This event must be one that satisfies the IDCMP flags of any open windows. If used
as a function, WaitEvent returns the IDCMP flag of the event (please refer to
DefaultIDCMP for a table of possible IDCMP flags). If used as a statement, you have
no way of telling what event occured.
You may find the window object number that caused the event using the EventWindow
In the case of events concerning gadgets or menus, further functions are available
to detect which gadget or menu was played with.
In the case of mouse button events, the MButtons function may be used to discover
exactly which mouse button has been hit.
IMPORTANT NOTE: If you are assigning the result of WaitEvent to a variable, MAKE
SURE that the variable is a long type variable.
For example: MyEvent.l=WaitEvent
Event works similarly to WaitEvent in that it returns the IDCMP flag of any
outstanding windows events. However, Event will NOT cause program flow to halt.
Instead, if no event has occured, Event will return 0.
EventWindow may be used to determine in which window the most recent window event
occured. Window events are detected by use of either the WaitEvent or Event
EventWindow returns the window object number in which the most recent window event
Flush Events [IDCMP_Flag]
When window events occur in Blitz, they are automatically 'queued' for you. This
means that if your program is tied up processing one window event while others are
being created, you wont miss out on anything. Any events which may have occured
between executions of WaitEvent or Event will be stored in a queue for later use.
However, there may be situations where you want to ignore this backlog of events.
This is what FlushEvents is for.
Executing FlushEvents with no parameters will completely clear Blitz's internal
event queue, leaving you with no outstanding events. Supplying an IDCMP_Flag
parameter will only clear events of the specified type from the event queue.
GadgetHit returns the identification number of the gadget that caused the most
recent 'gadget pushed' or 'gadget released' event.
As gadgets in different windows may possibly posess the same identification numbers,
you may also need to use EventWindow to tell exactly which gadget was hit.
MenuHit returns the identification number of the menu that caused the last menu
event. As with gadgets, you can have different menus for different windows with the
same identification number. Therefore you may also need to use EventWindow to find
which window caused the event.
If no menus have yet been selected, Menuhit will return -1.
ItemHit returns the identification number of the menu item that caused the last menu
SubHit returns the identification number of the the menu subitem that caused the
last menu event. If no subitem was selected, SubHit will return -1.
MButtons returns the codes for the mouse buttons that caused the most recent 'mouse
If menus have been turned off using Menus Off, then the right mouse button will also
register an event and can be read with MButtons.
RawKey returns the raw key code of a key that caused the most recent 'key press'
Qualifier will return the qualifier of the last key that caused a 'key press' event
to occur. A qualifier is a key which alters the meaning of other keys; for example
the 'shift' keys. Here is a table of qualifier values and their equivalent keys:
Key Left Right
UnQualified $8000 $8000
Shift $8001 $8002
Caps Lock Down $8004 $8004
Control $8008 $8008
Alternate $8010 $8020
Amiga $8040 $8080
A combination of values may occur, if more that one qualifier key is being held
down. The way to filter out the qualifiers that you want is by using the logical AND
WPlot plots a pixel in the currently used window at the coordinates X,Y in the
colour specified by Colour.
WBox draws a solid rectangle in the currently used window.
The upper left hand coordinates of the box are specified with the Xl and Yl values,
and the bottom right hand corner of the box is specified by the values X2 and Y2.
WCircle allows you to draw a circle in the currently used window. You specify the
centre of the circle with the coordinates X,Y. The Radius value specifies the radius
of the circle you want to draw. The last value, Colour specifies what colour the
circle will be drawn in.
WEllipse X,Y,X Radius,Y Radius,Colour
WEllipse draws an ellipse in the currently used window. You specify the centre of
the ellipse with the coordinates X,Y. X Radius specifies the horizontal radius of
the ellipse, Y Radius the vertical radius.
Colour refers to the colour in which to draw the ellipse.
Wline allows you to draw a line or a series of lines into the currently used window.
The first two sets of coordinates X1,Y1,X2,Y2, specify the start and end points of
the initial line. Any coordinates specified after these initial two, will be the end
points of another line going from the last set of end points, to this set. Colour is
the colour of the line(s) that are to be drawn.
WCls will clear the currently used window to colour 0, or a colour is specified,
then it will be cleared to this colour. If the current window was not opened with
the GIMMEZEROZERO flag set, then this statement will clear any border or title bar
that the window has. The InnerCls statement should be used to avoid these side
InnerCls will clear only the inner portion of the currently used window. It will not
clear the titlebar or borders as WCls would do if your window was not opened with
the GIMMEZEROZERO flag set. If a colour is specified, then that colour will be used
to clear the window.
WScroll X1,Y1,X2,Y2,Delta X,Delta Y
WScroll will cause a rectangular area of the currently used window to be moved or
'scrolled'. X1 and Y1 specify the top left location of the rectangle, X2 and Y2 the
bottom right. The Delta parameters determine how far to move the area. Positive
values move the area right/down, while negative values move the area left/up.
Cursor will set the style of cursor that appears when editing strings or numbers
with the Edit$ or Edit functions. If Thickness is less than 0, then a block cursor
will be used. If the Thickness is greater then 0, then an underline Thickness pixels
high will be used.
After executing an Edit$ or Edit function, Editat may be used to determine the
horizontal character position of the cursor at the time the function was exited.
Through the use of Editat, EditExit, EditFrom and Edit$, simple full screen editors
may be put together.
EditFrom allows you to control how the Edit$ and Edit functions operate when used
If a Characterpos parameter is specified, then the next time an edit function is
executed, editing will commence at the specified character position (0 being the
first character position).
Also, editing may be terminated not just by the use of the 'return' key, but also by
any non printable character (for example, 'up arrow' or 'Esc') or a window event.
When used in conjunction with Editat and EditExit, this allows you to put together
simple full screen editors.
If Characterpos is omitted, Edit$ and Edit return to normal - editing always
beginning at character postition 0, and 'return' being the only way to exit.
EditExit returns the ASCII value of the character that was used to exit a window
based Edit$ or Edit function. You can only exit the edit functions with keypresses
other than 'return' if EditFrom has been executed prior to the edit call.
WindowFont sets the font for the currently used window. Any further printing to this
window will be in the specified font. IntuiFont# specifies a previously initialized
intuifont object created using LoadFont.
WColour Foreground Colour[,Background Colour]
WColour sets the foreground and background colour of printed text for the currently
used window. Any further text printed on this window will be in these colours.
WJam sets the text drawing mode of the currently used window. These drawing modes
allow you to do inverted, complemented and other types of graphics. The drawing
modes can be OR'ed together to create a combination of them.
This draws only the foreground colour and leaves the background transparent. Eg For
the letter 0, any empty space (inside and outside the letter) will be transparent.
This draws both the foreground and background to the window. Eg With the letter 0
again, the 0 will be drawn, but any clear area (inside and outside) will be drawn in
the current background colour.
This will exlusive or (XOR) the bits of the graphics.
This allows the display of inverse video characters. If used in conjunction with
Jam2, it behaves like Jam2, but the foreground and background colours are exchanged.
Activate will activate the window specified by Window#.
The Menus command may be used to turn ALL menus either on or off. Turning menus off
may be useful if you wish to read the right mouse button.
WPointer allows you to determine the mouse pointer imagery used in the currently
used window. Shape# specifies an initialized shape object the pointer is to take
it's appearance from, and must be of 2 bitplanes depth (4 colours).
WMove will move the current window to screen position X,Y.
WSize will alter the width and height of the current window to the values specified
by Width and Height.
WMouseX returns the horizontal x coordinate of the mouse relative to the left edge
of the current window. If the current window was opened without the GIMMEZEROZERO
flag set, then the left edge is taken as the left edge of the border around the
window, otherwise, if GIMMEZEROZERO was set, then the left edge is the taken from
inside the window border.
WMouseY returns the vertical y coordinate of the mouse relative to the top of the
current window. If the current window was opened without the GIMMEZEROZERO flag set,
then the top is taken as the top of the border around the window, otherwise, if
GIMMEZEROZERO was set, then the top is taken trom inside the window border.
EMouseX will return the horizontal position of the mouse pointer at the time the
most recent window event occured. Window events are detected using the WaitEvent or
EMouseY will return the vertical position of the mouse pointer at the time the most
recent window event occured. Window events are detected using the WaitEvent or Event
WCursX returns the horizontal location of the text cursor of the currently used
window. The text cursor position may be set using WLocate.
WCursY returns the vertical location of the text cursor of the currently used
window. The text cursor position may be set using WLocate.
WLocate is used to set the text cursor position within the currently used window. X
and Y are both specified in pixels as offsets from the top left of the window. Each
window has it's own text cursor position, therefore changing the text cursor
position of one window will not affect any other window's text cursor position.
WindowX returns the horizontal pixel location of the top left corner of the
currently used window, relative to the screen the window appears in.
WindowY returns the vertical pixel location of the top left corner of the currently
used window, relative to the screen the window appears in.
WindowWidth returns the pixel width of the currently used window.
WindowHeight returns the pixel height of the currently used window.
InnerWidth returns the pixel width of the area inside the border of the currently
InnerHeight returns the pixel height of the area inside the border of the currently
WTopOff returns the number of pixels between the top of the current window border
and the inside of the window.
WLeftOff returns the number of pixels between the left edge of the current window
border and the inside of the window.
SizeLimits Min Width,Min Height,Max Width,Max Height
SizeLimits sets the limits that any new windows can be sized to with the sizing
gadget. After calling this statement, any new windows will have these limits imposed
RastPort returns the specified Window's RastPort address. Many commands in the
graphics.library and the like require a RastPort as a parameter.
PositionSuperBitMap is used to display a certain area of the bitmap in a super
After rendering changes to a superbitmap window the bitmap attached can also be
updated with the GetSuperBitMap. After rendering changes to a bitmap the superbitmap
window can be refreshed with the PutSuperBitMap command. Both commands work with the
currently used window.
See GetSuperBitmap description.
WTitle is used to alter both the current window's title bar and it's screens title
bar. Useful for displaying important stats such as program status etc.
CloseWindow has been added for convenience. Same as Free Window but a little more
intuitive (added for those that have complained about such matters).
WPrintScroll will scroll the current window upwards if the text cursor is below the
bottom of the window and adjust the cursor accordingly. Presently WPrintScroll only
works with windows opened with the gimme00 flag set (#gimmezerozero=$400).
WBlit can be used to blit any shape to the current window. Completely system
friendly this command will completely clip the shape to fit inside the visible part
of the window Use GimmeZeroZero windows for clean clipping when the window has
BitMaptoWindow will copy a bitmap to a window in an operating system friendly manner
(what do you expect). The main use of such a command is for programs which use the
raw bitmap commands such as the 2D and Blit libraries for rendering bitmaps quickly
but require a windowing environment for the user interface.
EventCode returns the actual code of the last Event received by your program,
EventQualifier returns the contents of the Qualifier field. Of use with the new
GadTools library and some other low level event handling requirements.
Similar to ScreenTags, WindowTags allows the advanced user to open a Blitz window
with a list of OS Tags as described in the documentation for the operating system
prior to 2.0.
LoadFont IntuiFont#,Fontname.font$,Y Size[,style]
LoadFont is used to load a font from the fonts: directory. Unlike BlitzFonts any
size IntuiFont can be used. The command WindowFont is used to set text output to a
certain IntuiFont in a particular Window.
The LoadFont command has been extended with an optional style parameter. The
following constants may be combined:
#extended=8 ;wider than normal
#colour=64 ;hmm use colour version I suppose