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 events system. 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 accordingly. 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 Window#,X,Y,Width,Height,Flags,Title$,Dpen,Spen[,GadgetList#] 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 in pixels. 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 window title. 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 specified window. 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 Window# 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 is executed. 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 Window# 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 is executed. 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 IDCMP_Flags 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 functions. 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. IDCMP FlagEvent $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 IDCMP_Flags 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 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 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 function. 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 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 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 commands. EventWindow returns the window object number in which the most recent window event occured 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 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 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 ItemHit returns the identification number of the menu item that caused the last menu event. SubHit 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 MButtons returns the codes for the mouse buttons that caused the most recent 'mouse buttons' event. 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 RawKey returns the raw key code of a key that caused the most recent 'key press' evens. Qualifier 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 operator. WPlot X,Y,Colour WPlot plots a pixel in the currently used window at the coordinates X,Y in the colour specified by Colour. WBox X1,Y1,X2,Y2,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 X,Y,Radius,Colour 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 X1,Y1,X2,Y2[,Xn,Yn..],Colour 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 [Colour] 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 effects.. InnerCls [Colour] 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 Thickness 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. Editat 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 [Characterpos] EditFrom allows you to control how the Edit$ and Edit functions operate when used within windows. 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 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 IntuiFont# 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 Jammode 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. Jam1=0 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. Jam2=1 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. Complement=2 This will exlusive or (XOR) the bits of the graphics. Inversvid=4 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 Window# Activate will activate the window specified by Window#. Menus On|Off 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 Shape# 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 X,Y WMove will move the current window to screen position X,Y. WSize Width,Height WSize will alter the width and height of the current window to the values specified by Width and Height. WMouseX 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 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 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 Event commands. EMouseY 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 commands. WCursX WCursX returns the horizontal location of the text cursor of the currently used window. The text cursor position may be set using WLocate. WCursY WCursY returns the vertical location of the text cursor of the currently used window. The text cursor position may be set using WLocate. WLocate X,Y 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 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 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 WindowWidth returns the pixel width of the currently used window. WindowHeight WindowHeight returns the pixel height of the currently used window. InnerWidth InnerWidth returns the pixel width of the area inside the border of the currently used window. InnerHeight InnerHeight returns the pixel height of the area inside the border of the currently used window. WTopOff WTopOff returns the number of pixels between the top of the current window border and the inside of the window. WLeftOff 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 on them. RastPort (Window#) RastPort returns the specified Window's RastPort address. Many commands in the graphics.library and the like require a RastPort as a parameter. PositionSuperBitMap x,y PositionSuperBitMap is used to display a certain area of the bitmap in a super bitmap window. GetSuperBitMap 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. PutSuperBitMap See GetSuperBitmap description. WTitle windowtitle$,screentitle$ 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 Window# 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 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 Shape#,x,y 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 title/sizing gadgets. BitMaptoWindow Bitmap#,Window#[,srcx,srcy,destx,desty,wid,height] 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 EventCode returns the actual code of the last Event received by your program, EventQualifier EventQualifier returns the contents of the Qualifier field. Of use with the new GadTools library and some other low level event handling requirements. WindowTags Window#,Flags,Title$,[&TagList]|[[Tag,Data]...] 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: #underlined=1 #bold=2 #italic=4 #extended=8 ;wider than normal #colour=64 ;hmm use colour version I suppose