NitrOS-9 EOU Level 2 Windowing System Manual
The NitrOS-9 EOU Project http://www.lcurtisboyle.com/nitros9/nitros9.html
The NitrOS-9 project: http://sourceforge.net/projects/nitros9/
1
The NitrOS-9 EOU Level 2 Windowing System Manual
Revision History:
Revision 0.30
0.21
0.2
Date December 3,2020
July 2, 2020
May 19, 2020
0.1
June 4, 2004
Comment CorrecDons, addiDons for EOU Beta 6 Minor addiDons about op- DmizaDons.
Updated to reflect changes to NitrOS-9 over Dme and specifically to cover changes related to the EOU (“Ease of Use”) project.
Created
Acknowledgements:
2004 revision by: Bob Emery and Boisy Pitre.
2020 revision addiDons and correcDons by: L.
CurDs Boyle and Jay Searle
2
The NitrOS-9 EOU Level 2 Windowing System Manual
Table Of Contents
……………………………………………………………………………………………………………………………………1 NitrOS-9 EOU Level 2 Windowing System Manual……………………………………………………………1 Table Of Contents……………………………………………………………………………………………………..3 Chapter 1.
The NitrOS-9 Level 2 Windowing System…………………………………………………………5 Device Windows………………………………………………………………………………………………………..6 Opening a Device Window………………………………………………………………………………………6 Overlay Windows……………………………………………………………………………………………………….9 Opening an Overlay Window…………………………………………………………………………………..9 Chapter 2.
Overview of Commands and Parameters………………………………………………………..10 Parameters……………………………………………………………………………………………………………..10 Chapter 3.
General Commands…………………………………………………………………………………….13 Bcolor………………………………………………………………………………………………………14 BoldSw…………………………………………………………………………………………………….15 Border……………………………………………………………………………………………………..16 CWArea…………………………………………………………………………………………………..17 DefColr…………………………………………………………………………………………………….18 DfnGPBuf…………………………………………………………………………………………………19 DWEnd……………………………………………………………………………………………………23 DWProtSw……………………………………………………………………………………………….24 DWSet…………………………………………………………………………………………………….25 FColor……………………………………………………………………………………………………..27 Font…………………………………………………………………………………………………………28 GCSet……………………………………………………………………………………………………..31 GetBlk……………………………………………………………………………………………………..32 GPLoad……………………………………………………………………………………………………33 KilBuf………………………………………………………………………………………………………34 LSet………………………………………………………………………………………………………..35 OWEnd……………………………………………………………………………………………………37 OWSet…………………………………………………………………………………………………….38 Palette……………………………………………………………………………………………………..40 PropSw……………………………………………………………………………………………………42 PSet………………………………………………………………………………………………………..43 PutBlk……………………………………………………………………………………………………..46 ScaleSw…………………………………………………………………………………………………..47 Select………………………………………………………………………………………………………48 TCharSw………………………………………………………………………………………………….49 Chapter 4.
Drawing Commands…………………………………………………………………………………….50 Arc3P………………………………………………………………………………………………………51 Bar………………………………………………………………………………………………………….52 RBar………………………………………………………………………………………………………..52 Relative Draw Bar……………………………………………………………………………………..52 Box………………………………………………………………………………………………………….53 RBox……………………………………………………………………………………………………….53 Circle……………………………………………………………………………………………………….54 Ellipse……………………………………………………………………………………………………..55 FFill…………………………………………………………………………………………………………56 FCircle…………………………………………………………………………………………………….58 FEllipse……………………………………………………………………………………………………59 Line…………………………………………………………………………………………………………60
3
The NitrOS-9 EOU Level 2 Windowing System Manual
Rline………………………………………………………………………………………………………..60 LineM………………………………………………………………………………………………………61 RLineM……………………………………………………………………………………………………61 Point………………………………………………………………………………………………………..62 RPoint……………………………………………………………………………………………………..62 PutGC……………………………………………………………………………………………………..63 SetDPtr……………………………………………………………………………………………………64 RSetDPtr………………………………………………………………………………………………….64 Chapter 5.
Text Commands…………………………………………………………………………………………..65 Optimization Tips:………………………………………………………………………………………………………..66 Alphabetical Index……………………………………………………………………………………………………….67
4
The NitrOS-9 EOU Level 2 Windowing System Manual
Chapter 1.
The NitrOS-9 Level 2 Windowing System
One of NitrOS-9 Level 2’s advanced features is its built-in Windowing System.
The Win- dowing System allows you to lay one or more rectangular areas, called windows, on top of your exisDng screen display.
These smaller areas can take up a porDon of the screen, or uDlize an enDre screen area.
With these windows, you can watch several tasks perform at the same Dme.
For exam- ple, suppose you are wriDng a business le‘er using a word processor in one window.
You can go to a spreadsheet program in another window, get a price quote you need, return to the word processor, and include the price in the le‘er.
In yet another win- dow, a terminal program connected to a modem could be downloading a program or data file.
There are a number of opDons that windows give to your applicaDon and work environ- ments: they can be text only or contain a combinaDon of text and graphics.
Separate text, drawing and background colors can be selected as well to provide a parDcular color style.
The ability to customize your window to suite your working environment and preferences is easy to do and puts the power of windowing at your fingerDps.
The Windowing System allows as many windows as your computer's memory can sup- port, with a maximum of 32 available at one Dme, including overlay windows.
Support for the windowing system comes from several modules:
• CoGrf – Handles the parsing of display codes for window creaDon and manipula-
Don.
• CoWin – Performs the same funcDons as CoGrf, but also adds in enhanced win-
dow border and mouse control funcDonality (use only CoGrf or CoWin in your sys- tem, not both!)
• GrfDrv – This module is located in the CMDS directory of your boot disk and is re- sponsible for carrying out the actual drawing and bitmap manipulaDon funcDons.
It is automaDcally loaded as needed by NitrOS-9.
5
The NitrOS-9 EOU Level 2 Windowing System Manual
In NitrOS-9, there are two types of windows: device windows and overlay windows.
Device Windows A device window is one that can run a program or uDlity.
This is the type of window you would use in the word processor/spreadsheet example given above.
Each device win- dow acts as an individual terminal.
The device windows are designated as devices /w1 - /w15.
You open a device window as you do any other NitrOS-9 device and specify the window's parameters, including whether the window is for text or graphics.
If you want to run a process in the window, you can start an execuDon environment, such as a shell, on the window.
(See “Opening a Device Window,” later in this chapter, and the DWSet command in Chapter 3.)
Note: If you want only to send output to the device window without running a process in the window, do not start a shell on the window.
Device windows cannot overlay each other, and their boundaries cannot overlap.
Opening a Device Window
To open a device window, follow these steps:
1.
First, we must allocate memory for the window.
Use NitrOS-9's iniz command to
iniDalize window 7 in this example.
Type:
iniz /w7
ENTER
2.
Next, send an escape sequence to the window that tells it the parameters you want.
These parameters include the screen type, size, and colors.
For example:
wcreate /w7 -s=2 20 10 40 10 01 00 00 OR display 1b 20 2 14 0a 28 0a 01 00 00>/w7
ENTER
ENTER
6
The NitrOS-9 EOU Level 2 Windowing System Manual
sends the DWSet command escape sequence to the /w7 window.
The wcreate command insists that you use decimal numbers, while the display command can take both decimal and hexadecimal numbers.
The funcDons of the codes, as used in the wcreate command, are as follows:
2
20
10
40
10
01
00
00
Sets a screen type of 80 x 24 (text only)
Starts the window at character/column 20
Starts the window at line/row 10
Sets a window size of 40 characters
Sets a window height of 10 lines
Sets the foreground color to blue
Sets the background color to white
Sets the border color to white
If you do not send escape sequences, NitrOS-9 uses default descriptors for the windows.
The window size defaults are:
Window Number Term 1 2 3
Screen Type (chars/line) 40 (text) 80 (text) 80 (text) 80 (text)
StarLng PosiLon (horizontal, verLcal) 0,0 0,0 0,0 0,0
Size (columns, rows) 40,25 80,25 80,25 80,25
7
The NitrOS-9 EOU Level 2 Windowing System Manual
4 5 6 7 8 9 10 11 12 13 14 15
80 (text) 80 (text) 80 (text) 80 (text) 80 (text) 80 (text) 80 (text) 80 (text) 80 (text) 80 (text) 80 (text) 80 (text)
0,0 0,0 0,0 0,0 0,0 0,0 0,0 0,0 0,0 0,0 0,0 0,0
80,25 80,25 80,25 80,25 80,25 80,25 80,25 80,25 80,25 80,25 80,25 80,25
3.
Use NitrOS-9's shell command to fork a shell to the window.
Type:
shell i=/w7&
ENTER
The i= parameter creates an immortal shell.
CreaDng an immortal shell protects the window and its shell from being destroyed if you accidentally exit the shell using CTRL
.
BREAK
You now have a window that can run its own tasks.
InformaDon displayed in that win- dow is automaDcally scaled to the window's size.
8
The NitrOS-9 EOU Level 2 Windowing System Manual
Overlay Windows An overlay window is a window that you open on top of a device window.
(You can place overlay windows over other overlay windows, but there must always be a device window at the bo‘om of the stack.) The purpose of overlay windows is to display com- puter dialog.
You cannot fork a shell to an overlay window; however, you can run a shell in an overlay window.
Overlay windows assume the screen type of the device windows they overlay.
Opening an Overlay Window
To open an overlay window, use the Overlay Window Set funcDon.
(See OWSet in Chapter 3., “General Commands”)
9
The NitrOS-9 EOU Level 2 Windowing System Manual
Chapter 2.
Overview of Commands and Parameters
The windowing commands are divided among three chapters, based on their funcDons.
Chapter 3.
describes the general commands.
These commands let you create windows and buffers, access buffers, set switches, and maintain the window environment.
Chapter 4.
describes the drawing commands.
Besides leong you draw all kinds of im- ages (circles, ellipses, arcs, and boxes, to name a few), these commands also enable you to color areas or to fill them with pa‘erns.
Chapter 5.
describes the text commands.
Use these commands to manipulate the text cursor and the text a‘ributes.
Text commands operate on hardware text screens (screen types 1 and 2) and graphics windows if a font is selected.
Each command descripDon lists the command's name, code, and parameters.
To call a Windowing System command using NitrOS-9's display command, type display, followed by the command code and the values you want to supply for the parameters.
Parameters The following is a complete list of the parameter abbreviaDons used in Chapters 3, 4, and 5.
All parameters represent a single byte of informaDon.
Parameter HBX LBX HBY LBX HBXo LBXo HBYo LBYo HBR LBR
DescripLon high order byte of x value low order byte of x value high order byte of y value low order byte of y value high order byte of x-offset value (relaGve) low order byte of x-offset value (relaGve) high order byte of y-offset value (relaGve) low order byte of y-offset value (relaGve) high order byte of radius low order byte of radius
10
The NitrOS-9 EOU Level 2 Windowing System Manual
HBL LBL HSX LSX HSY LSY HBRx LBRx GRP BFN LCN PRN CTN FNM CPX CPY STY SVS
SZX SZY XDR YDR BSW
high order byte of length low order byte of length high order byte of size in x direcGon low order byte of size in x direcGon high order byte of size in y direcGon low order byte of size in y direcGon high order byte of radius in x direcGon low order byte of radius in x direcGon GET/PUT buffer group number (1-254) GET/PUT buffer number (1-255) logic code number paleQe register number (0-15, wraps mod 16) color table number (0-63, wraps mod 64) font number character posiGon x (0-xmax) character posiGon y (0-ymax) screen type save switch (0 = no save, 1 = save area under overlay) size in x (columns) size in y (rows) dimension raGo x used with YDR as YDR/XDR dimension raGo y binary switch (0 = off, 1 = on)
11
Chapter 3.
General Commands
The general commands let you set up and customize windows.
They also let you set up and access image buffers and select colors for the screen.
13
Bcolor Background Color
Code: 1B 33
Parameters: PRN
FuncLon: Lets you choose a color pale‘e register to use as the background color.
See the Pale‘e command for seong up the actual colors.
14
BoldSw Bold Switch
Code: 1B 3D
Parameters: BSW
FuncLon: Enables or disables boldfacing for text on graphics screens.
If boldface is on, the screen displays subsequent characters in bold.
If boldface is off, the screen displays subsequent characters in the regular font.
BSW = switch
00 = off (Default) 01 = on
Notes:
• You can use BoldSw with any font.
• Boldface is not supported on hardware text screens (screen types 1 and 2).
15
Border Screen Color
Code: 1B 34
Parameters: PRN
Notes:
FuncLon: Lets you change the pale‘e register used for the screen border.
See the Pal- e‘e command for seong up the actual colors.
• You set the border by selecDng a pale‘e register to use for the border register.
When the actual color is changed in the pale‘e register selected by the com- mand, the color of the screen border changes to the new color.
In general, the border register usually matches the background pale‘e register.
16
FuncLon: Lets you alter the working area of the window.
Normally, the system uses this call for high-level windowing, but you can use it to restrict output to a smaller area of the window.
CWArea Change Working Area
Code: 1B 25
Notes:
Parameters: CPX CPY SZX SZY
• You cannot change a window's working area to be larger than the predefined-area
of the window as set by DWSet or OWSet.
• All drawing and window updaDng commands are done on the current working area of a window.
The working area defaults to the enDre size of the window.
Scaling, when in use, is also performed relaDve to the current working area of a window.
The CWArea command allows users to restrict the working area of a window to smaller than the full window size.
FuncDons that might be performed by opening a non-saved overlay window to draw or clear an image and then closing the overlay can be accomplished by using this command to shorten execuDon Dme where an actual overlay window is not needed.
17
DefColr Default Color
Code: 1B 30
Parameters: None
Notes:
plays.
FuncLon: Sets the pale‘e registers back to their default values.
The actual values of the pale‘e registers depend on the type of monitor you are using.
(See montype in NitrOS-9 Commands Reference.)
• The default color definiDons apply only to high-resoluDon graphics and text dis-
• The system sets the pale‘e registers to a proper compaDbility mode when switch-
ing to screens using the older VDG emulaDon modes.
See the table below:
Window System
Color Modes
VDG-CompaLble Modes
PaleQe 00 & 08 01 & 09 02 & 10 03 & 11 04 & 12 05 & 13 06 & 14 07 & 15
Color White Blue Black Green Red Yellow Magenta Cyan
P# Color 00 Green 01 Yellow 02 Blue 03 Red 04 Buff 05 Cyan 06 Magenta 07 Orange
P# Color 08 Black 09 Green 0A Black 0B Buff 0C Black 0D Green 0E Black 0F Orange
• The SetStat call lets you change the default color pale‘e definiDon when using the windowing system.
Default colors in the VDG-CompaDble Mode cannot be changed.
See the NitrOS-9 Technical Reference manual for informaDon on SetStat.
• The system's default colors are used whenever you create a new window.
18
DfnGPBuf Define GET/PUT Buffer
FuncLon: Lets you define the size of the GET/PUT buffers for the system.
Once you allo- cate a GET/PUT buffer, it remains allocated unDl you use the KilBuf command to delete it.
NitrOS-9 allocates memory for GET/PUT buffers in 8K blocks that are then divided into the different GET/PUT buffers.
Buffers are divided into buffer groups.
Therefore, all commands dealing with GET/PUT buffers must specify both a group number and a buf- fer number within that group.
Code: 1B 29
Parameters: GRP BFN HBL LBL
Technical: The buffer usage map is as follows:
Group Number
0 1-199 200-254
255
Buffer
Number1 1-255 1-255 1-255 1-255
Use
Internal use only (returns errors) General use by applicaDons2 Reserved Internal use only for overlay windows (returns errors)
Note: The names, buffer groups, and buffer numbers are defined in the assembly defini- Don file.
The decimal number you use to call these are in parentheses next to the name.
For example, to select the Arrow pointer, Grp_Ptr and Ptr_Arr, you use 202,1 as the group/buffer number.
The standard group numbers are defined as follows:
1 Buffer Number 0 is invalid and cannot be used.
2 The applicaDon program should request its user ID via the GETID system call to use as its group number for buffer allocaDon.
19
Grp_Fnt(200) = font group for system fonts Fnt_S8x8(1) = standard 8×8 font Fnt_S6x8(2) = standard 6×8 font Fnt_G8x8(3) = standard graphics font
A complete list of current fonts can be found in dd/sys/fontlist.txt
The standard fonts are in the file SYS/StdFonts.
Grp_Clip(201) = clipboarding group (for MulD-Vue, MVCanvas, etc.) Grp_Ptr(202) = graphics cursor (pointer) group
Ptr_Arr(1) = arrow pointer (hp = 0,0) Ptr-Pen(2) = pencil pointer (hp = 0,0) Ptr_LCH(3) = large cross hair pointer (hp = 7,7) Ptr_Slp(4) = sleep indicator (hourglass) Ptr_Ill(5) = illegal indicator Ptr-Txt(6) = text pointer (hp = 3,3) Ptr_SCH(7) = small cross hair pointer (hp = 3,3) hp=hit point, the coordinates of the actual point on the object at which the cursor should be centered.
The standard pointers are in the file SYS/StdPtrs.
Grp_Pat2(203) = two color pa‘erns Grp_Pat4(204) = four color pa‘erns Grp_Pat6(205) = sixteen color pa‘erns Pat_Dot(1) = dot pa‘ern Pat_Vrt(2) = verDcal line pa‘ern Pat_Hrz(3) = horizontal line pa‘ern Pat_XHtc(4) = cross hatch pa‘ern Pat_LSnt(5) = lew slanted lines Pat_RSnt(6) = right slanted lines Pat_SDot(7) = small dot pa‘ern Pat_BDot(8) = large dot pa‘ern
NEW TO BETA 6 – EXTENDED PATTERNS (USED IN MVCANVAS)
Pat.Bubl(9) = bubble pa‘ern
20
Pat.Bskt(10) = basket weave pa‘ern Pat.Wafl(11) = waffle iron pa‘ern Pat.Shng(12) = shingle pa‘ern Pat.Bric(13) = brick pa‘ern Pat.SmGr(14) = small grid pa‘ern Pat.Dmnd(15) = Diamond floor pa‘ern Pat.Flor(16) = floor Dle pa‘ern
Each pa‘ern is found within each of the pa‘ern groups.
Standard pa‘erns are in the files: SYS/StdPats_2, SYS/StdPats_4, and SYS/StdPats_16.
Extended pa‘erns are in the files: SYS/StdPats_2.plus, SYS/StdPats_4.plus, and SYS/StdPats_16.plus.
Grp.Wnd(206) = MulD-Vue / Gshell Extended 4 color 3D look characters
Wnd.UpAr(1) = Up arrow 3D look Wnd.DnAr(2) = Down arrow 3D look Wnd.LtAr(3) = Lew arrow 3D look Wnd.RtAr(3) = Right arrow 3D look Wnd.VBar(3) = VerDcal scroll bar marker 3D look Wnd.HBar(3) = Horizontal scroll bar marker 3D look
Grp.Cd16(207) = 16 color playing card set (courtesy of Paul Shoemaker)
These are buffer numbers 1-54: 1=Card back 2-14=(Ace to King of Diamonds) 15-27=(Ace to King of Hearts) 28-40=(Ace to King of Spades) 41-53=(Ace to King of Clubs) 54=Joker 55=Empty card slot
NOTE: EOU Beta 6 and up now also pre-load the MVCanvas extended pa‘erns.
The 16 color card playing set is NOT pre-loaded, but available for use in SYS/CARDDECK.
Each card image has it’s own buffer, so you only need to load the specific cards that you need for a parDcular card game, if you wish.
All files have GPLoad commands imbedded in file, along with the data.
To load fonts, pointers, or pa‘erns, simply merge them to any window device: For example:
21
merge SYS/StdFonts ENTER
sends the standard font to standard output which may be redirected to another device if the current output device is not a window device (such as when term is a VDG screen).
You only need to load fonts once for the enDre system.
Once a GET/PUT buffer is loaded, it is available to all devices and processes in the system.
NitrOS-9 EOU Beta 2 and up specific: NitrOS-9 EOU Beta 2 and up specific:
By default, the EOU preloads all fonts for you, so you have access to all of By default, the EOU preloads all fonts for you, so you have access to all of
them in your programs.
them in your programs.
22
FuncLon: Ends a current device window.
DWEnd closes the display window.
If the win- dow was the last device window on the screen, DWEnd also deallocates the memory used by the window.
If the window is an interacDve window, NitrOS-9 automaDcally switches you to a new device window, if one is available.
DWEnd Device Window End
Code: 1B 24
Parameters: None
Notes:
• DWEnd is only needed for windows that have been a‘ached via the iniz uDlity or the I$A‘ach system call.
Non-a‘ached windows have an implied DWEnd com- mand that is executed when you close the path.
23
DWProtSw Device Window Protect Switch
FuncLon: Disables and enables device window protecDon.
By default, device windows are protected so that you cannot overlay them with other device windows.
This type of protecDon helps avoid the possibility of destroying the contents of either or both win- dows.
Code: 1B 36
Parameters: BSW
Notes:
BSW = switch 00=off 01 = on (Default)
• We recommend that you not turn off device window protecDon.
If you do, how- ever, use extreme discreDon because you might destroy the contents of the win- dows.
NitrOS-9 does not return an error if you request that a new window be placed over an area of the screen which is already in use by an unprotected win- dow.
• GShell uses this command to create an underlying, non-protected device window underneath it's resizable protected device windows, to allow you to posiDon mul- Dple device windows on the same screen, and you can use this technique as well.
24
FuncLon: Lets you define a window's size and locaDon on the physical screen.
Use DWSet awer opening a path to a device window.
DWSet Device Window Set
Parameters: STY CPX CPY SZX SZY PRN1 PRN2 PRN3
PRN 1 = Foreground PRN2 = Background PRN3 = Border (if STY >= 1)
Code: 1B 20
Notes:
• The iniz and display commands open paths to the device window.
• When using DWSet in a program, you must first open the device.
If you are
changing the window type of your current window, you must issue a DWEnd first.
• Output to a new window is ignored unDl NitrOS-9 receives a DWSet command, unless defaults are present in the device descriptor (/w1-/w15).
If defaults are present in the device descriptors, NitrOS-9 automaDcally executes DWSet, using those defaults.
• When NitrOS-9 receives the DWSet command, it allocates memory for the win-
dow, and clears the window to the current background color.
If the standard font is already in memory, NitrOS-9 assigns it as the default font.
If the standard font is not in memory, you must execute a font set (Font) command awer loading the fonts to produce text output on a graphics window.
If you do not have a font loaded, all characters will show as periods '.'
• Use the Screen Type code (STY) to define the resoluDon and color mode of the new screen.
If the screen type code is zero, NitrOS-9 opens the window on the process's currently selected screen.
If the code is 255 ($FF), NitrOS-9 opens the window on the currently displayed screen.
If the code is non-zero, NitrOS-9 allo- cates a new screen for the window.
25
The following describes the acceptable screen types:
Colors
Memory
Type
Code 255 00 01 02 05 06 07 08
Screen Size Current Displayed Screen3 Process's Current Screen 40 x 25 80 x 25 640 x 200 320 x 200 640 x 200 320 x 200
8 & 8 8 & 8 2 4 4 16
2000 4000 16000 16000 32000 32000
Text Text Graphics Graphics Graphics Graphics
Note: The GIME has a bug and will only show 199 lines in modes 05-08, but the 200th line is there and will show up when scrolling upwards.
• The locaDon of the window on the physical screen is determined by the diagonal
line defined by:
(CPX,CPY) and (CPX + SZX, CPY + SZY)
• The foreground, background, and border register numbers (PRN1, PRN2, and PRN3) define the pale‘e registers used for the foreground and background col- ors.
See the Pale‘e command in this chapter for more informaDon.
• When an implicit or explicit DWSet command is done on a window, the window
automaDcally clears to the background color.
• All windows on the screen must be of the same type (either text or graphics).
• Values in the pale‘e register affect all windows on the screen.
However, you can choose which register to use for foreground and background for each window.
That is, NitrOS-9 maintains pale‘e registers and border register numbers for the enDre screen and foreground and background registers numbers for each individ- ual window.
• NitrOS-9 deallocates memory for a screen when you terminate the last window
on that screen.
3 Use the Current Displayed Screen opDon only in procedure files to display several win- dows on the same physical screen.
All programs should operate on that process' current screen.
26
FColor Foreground Color
Code: 1B 32
Parameters: PRN
FuncLon: Lets you select a color pale‘e register for the foreground color.
See the Pale‘e command for seong the actual colors.
27
Font Select Font
Code: 1B 3A
Parameters: GRP BFN
Notes:
FuncLon: Lets you select/change the current font.
Before you can use this command, the font must be loaded into the specified GET/PUT group and buffer (using GPLoad).
See the GPLoad command for informaDon on loading font buffers.
• You can select proporDonal spacing for the font by using PropSw.
• All font data is a 2-color bit map of the font.
• Each character in the font data consists of 8 bytes of data.
The first byte defines the top scan line, the second byte defines the second scan line, and so on.
The high-order bit of each byte defines the first pixel of the scan line, the next bit de- fines the next pixel, and so on.
For example, the le‘er “A” would be represented like this:
Byte $10 $28 $44 $44 $7C $44 $44 $00
Pixel RepresentaLon .
.
.
# .
.
.
.
.
.
# .
# .
.
.
.
# .
.
.
# .
.
.
# .
.
.
# .
.
.
# # # # # .
.
.
# .
.
.
# .
.
.
# .
.
.
# .
.
.
.
.
.
.
.
.
.
Note that 6×8 fonts ignore the last 2 bits per byte.
• For fonts with 128 characters or less, the fonts are ordered with characters in the
following ranges:
$00-$1F
InternaDonal characters (see mapping below)
28
$20-$7F
Standard ASCII characters
InternaDonal characters or any characters in the font below character $20 (hex) are printed according to the following table:
Character posiLon in font
Char2
$00 $01 $02 $03 $04 $05 $06 $07 $08 $09 $0A $0B $0C $0D $0E $0F $10 $11 $12 $13 $14 $15 $16 $17 $18 $19 $1A $1B $1C $1D $1E $1F
$E1 $E2 $E3 $E4 $E5 $E6 $E7 $E8 $E9 $EA $EB $EC $ED $EE $EF $F0 $F1 $F2 $F3 $F4 $F5 $F6 $F7 $F8 $F9 $FA $BA $BB $BC $BD $BE $BF
Char1 or $C1 $C2 $C3 $C4 $C5 $C6 $C7 $C8 $C9 $CA $CB $CC $CD $CE $CF $D0 $D1 $D2 $D3 $D4 $D5 $D6 $D7 $D8 $D9 $DA $AA $AB $AC $AD $AE $AF
29
For 224 character fonts, Character posiDons $00 to $1F in the font map to character codes $E0 to $FF, and character posiDons $20 to $DF are the same character code as their posiDon.
NOTE: When you select a new font, the X posiDon of the text cursor is re- turned to 0 (as if a CR has occurred), and then the font takes effect.
30
GCSet Graphics Cursor Set
Code: 1B 39
Parameters: GRP BFN
Notes:
cursor.
ing buffer #.
FuncLon: Creates a GET/PUT buffer for defining the graphics cursor that the system dis- plays.
You must use GCSet to display a graphic cursor.
• To turn off the graphics cursor, specify GRP as 00.
• A system standard buffer or a user-defined buffer can be used for the graphics
• If you specify a buffer # that doesn’t exist, GCSet leaves it at the previously work-
31
GetBlk Get Block
Code: 1B 2C
FuncLon: Saves an area of the screen to a GET/PUT buffer.
Once the block is saved, you can put it back in its original locaDon or in another on the screen, using the PutBlk com- mand.
Parameters: GRP BFN HBX LBX HBY LBY HSX LSX HSY LSY
HBX/LBX = x-locaGon of block (upper le] corner) HBY/LBX = y-locaGon of block HSX/LSX = x-dimension of block HSY/LSY = y-dimension of block
Notes:
• The GET/PUT buffer maintains informaDon on the size of the block stored in the
buffer so that the PutBlk command works more automaDcally.
• If the GET/PUT buffer is not already defined, GetBlk creates it.
If the buffer is de- fined, the data must be equal to or smaller than the original size of the buffer.
• Original OS-9 Level 2 had a limit of not being able to do a GetBlk that was the full
width of the screen.
This is fixed in NitrOS-9.
NitrOS-9 EOU Beta 4 and up specific:
You are now allowed to use GetBlk/PutBlk with hardware text screens.
When doing this, you specify the X,Y start posiDons and sizes by character, not pixel.
You can also get and put between windows, but the window types and sizes currently MUST be the same type and size.
It will also currently wrap on the right hand side to one line lower on the lew side.
• It is recommended, for your own programs, to use the group number that corre- sponds to your process ID, so that you don't overwrite another programs buffers by accident.
Since some older programs do not clean up buffers themselves, you may also want to do a KilBuf for your group number with buffer 0 (Kill all get/put buffers) at the start of your program.
32
GPLoad GET/PUT Buffer Load
FuncLon: Preloads GET/PUT buffers with images that you can move to the screen later, using PutBlk.
If the GET/PUT buffer is not already created, GPLoad creates it.
If the buffer was previously created, the size of the passed data must be equal to or smaller than the original size of the buffer.
Otherwise, GPLoad truncates the data to the size of the buffer.
Parameters: GRP BFN STY HSX LSX HSY LSY HBL LBL (Data…)
STY = format HSX/LSX = x-dimension of stored block HSY/LSY = y-dimension of stored block HBL/LBL = number of bytes in data
Code: 1B 2B
Notes:
• Buffers are maintained in a linked list system.
• Buffers to be used most should be allocated last to minimize the search Dme in
finding the buffers.
• When loading a Font GET/PUT Buffer, the parameters are as follows:
GRP BFN STY HSX LSX HSY LSY HBL LBL (Data…)
GRP = 254 (note: not enforced, but HIGHLY recommended) STY = 5 HSX/LSX = x-dimension size of Font (6 or 8) HSY/LSY = y-dimension size of Font (8) HBL/LBL = size of first data (not including this header informaDon)
See the Font command for more informaDon on font data.
33
FuncLon: Deallocates the buffer specified by the group and buffer number.
To deallo- cate the enDre group of buffers, set the buffer number to 0.
KilBuf Kill GET/PUT Buffer
Code: 1B 2A
Parameters: GRP BFN
Notes:
• KilBuf returns memory used by the buffer to a free list.
When an enDre block of
memory has been put on the free list, the block is returned to the system.
• It is recommended that you use the same group number as your process ID num- ber, so that you don't change get/put buffers in other processes.
It is also recom- mended that you Kill the enDre group at the start of your program, since some older programs did not clean up buffers awer they were exited.
34
LSet Logic Set
Code: 1B 2F
Parameters: LCN
FuncLon: Lets you create special effects by specifying the type of logic used when stor- ing data, which represents an image, to memory.
The specified logic code is used by all draw commands unDl you either choose a new logic or turn off the logic operaDon.
To turn off the logic funcDon, set the logic code to 00.
LCN = logic code number
00 = No logic code; store new data on screen 01 = AND new data with data on screen 02 = OR new data with data on screen 03 = XOR new data with data on screen
Notes:
• The following tables summarize logic operaDons in bit manipulaDons:
AND
Result
OR
Result
First Operand 1 1 0 0
First Operand 1 1 0 0
Second Operand 1 0 1 0
Second Operand 1 0 1 0
1 0 0 0
1 1 1 0
35
XOR
Result
First Operand 1 1 0 0
Second Operand 1 0 1 0
0 1 1 0
• Data items are represented as pale‘e register numbers in memory.
Since logic is performed on the pale‘e register number and not the colors in the registers, you should choose colors for pale‘e registers carefully so that you obtain the desired results.
You may want to choose the colors for the pale‘e registers so that LSet appears to and, or, and xor the colors rather than the register numbers.
For exam- ple:
Pale_e # 0 1 2 3
Color White Blue Black Green
AlternaLve Order Black Blue Green White
36
OWEnd Overlay Window End
Code: 1B 23
Parameters: None
FuncLon: Ends a current overlay window.
OWEnd closes the overlay window and deallo- cates memory used by the window.
If you opened the window with a save switch value of hexadecimal 01, NitrOS-9 restores the area under the window.
If you did not, NitrOS- 9 does not restore the area and any further output is sent to the next lower overlay win- dow or to the device window, if no overlay window exists.
37
OWSet Overlay Window Set
FuncLon: Use OWSet to create an overlay window on an exisDng device window.
Ni- trOS-9 reconfigures current device window paths to use a new area of the screen as the current logical device window.
Code: 1B 22
Parameters: SVS CPX CPY SZX SZY PRN1 PRN2
SVS = save switch
00 = Do not save area overlayed , nor clear it.
01 = Save area overlayed and restore at close
PRN1 = foreground paleQe register PRN2 =background paleQe register
Notes:
• If you set SVS to zero, any writes to the new overlay window destroy the area un- der the window.
You might want to set SVS to zero if your system is already using most of its available memory.
You might also set SVS to zero whenever it takes relaDvely li‘le Dme to redraw the area under the overlay window once it is closed.
• If you have ample memory, specify SVS as 1.
Doing this causes the system to save the area under the new overlay window.
The system restores the area when you terminate the new overlay window.
(See OWEnd.)
• The size of the overlay window is specified in standard characters.
Use the same resoluDon (number of characters) as the device window that will reside beneath the overlay window.
Have your program determine the original size of the device window at startup (using the SS.ScSiz GETSTAT call), if the device window does not cover the enDre screen.
See the NitrOS-9 Technical Reference manual for in- formaDon on the SS.ScSiz GETSTAT call.
• Overlay windows can be created on top of other overlay windows; however, you can only write to the top most window.
Overlay windows are “stacked” on top of each other logically.
To get back down to a given overlay, you must close (OWEnd) any overlay windows that reside on top of the desired overlay window.
38
• Stacked overlay windows do not need to reside directly on top of underlying over- lay windows.
However, all overlay windows must reside within the boundaries of the underlying device window.
39
Pale_e Change Pale‘e
Code: 1B 31
Parameters: PRN CTN
Notes:
FuncLon: Lets you change the color associated with each of the 16 pale‘e registers.
• Changing a pale‘e register value causes all areas of the screen using that pale‘e register to change to the new color.
In addiDon, if the border is set to that pale‘e register, the border color also changes.
See the Border command for more infor- maDon.
• Colors are made up by seong the red, green, and blue bits in the color byte which
is inserted in the pale‘e register.
The bits are laid out as follows:
Bit 0 1 2 3 4 5 6 7
Color Blue low Green low Red low Blue high Green high Red high unused unused
40
By using six bits for color (2 each for red, green and blue) there is a possibility of 64 from which to choose.
Some of the colors are defined as shown:
White Black Standard Blue Standard Green Standard Red
: 00111111 = $3F (all color bits set) : 00000000 = $00 (no color bits set) : 00001001 = $09 (both blue bits set) : 00010010 = $12 (both green bits set) : 00100100 = $24 (both red bits set)
• These colors are for RGB monitors.
The composite monitors use a different color coding and do not directly match pure RGB colors.
To get composite color from the RGB colors, the system uses conversion tables.
The colors were assigned to match the RGB colors as close as possible.
There are, however, a wider range of composite colors, so the colors without direct matches were assigned to the clos- est possible match.
The white, black, standard green, and standard orange are the same in both RGB and composite.
41
FuncLon: Enables and disables the automaDc proporDonal spacing of characters.
Nor- mally, characters are not proporDonally spaced.
PropSw ProporDonal Switch
Code: 1B 3F
Parameters: BSW
Notes:
spaced.
BSW = switch
00 = off (Default) 01 = on
• Any standard sowware font used in a graphics screen can be proporDonally
• ProporDonal spacing is not supported on hardware text screens.
42
PSet Pa‘ern Set
Code: 1B 2E
Parameters: GRP BFN
Notes:
FuncLon: Selects a preloaded GET/PUT buffer as a pa‘ern RAM array.
This pa‘ern is used with all draw commands unDl you either change the pa‘ern or turn it off by passing a parameter of 00 as GRP (Group Number).
• The pa‘ern array is a 32 x 8 pixel representaDon of graphics memory.
The color
mode defines the number of bits per pixel and pixels per byte.
So, be sure to take the current color mode into consideraDon when creaDng a pa‘ern array.
• The GET/PUT buffer can be of any size, but only the number of bytes as described
by the following table are used:
Color Mode Size of Pa_ern Array 2 4 16
4 bytes x 8 = 32 bytes (1 bit per pixel) 8 bytes x 8 = 64 bytes (2 bits per pixel) 16 bytes x 8 = 128 bytes (4 bits per pixel)
• The buffer must contain at least the number of bytes required by the current color mode.
If the buffer is larger than required, the extra bytes are ignored.
• To turn off pa‘erning, set GRP to 00.
• The following example creates a two color pa‘ern of verDcal lines.
A two color pa‘ern is made up of 1’s and 0’s.
The diagram below shows the bit set pa‘ern (note that one pixel is equal to one bit):
10101010101010101010101010101010 10101010101010101010101010101010 10101010101010101010101010101010 10101010101010101010101010101010 10101010101010101010101010101010 10101010101010101010101010101010
43
10101010101010101010101010101010 10101010101010101010101010101010
When the binary for the 2×8 pixel data is compressed into byte data, noDce that each row consists of four bytes of data.
The pa‘ern now looks like this:
$55 $55 $55 $55 $55 $55 $55 $55 $55 $55 $55 $55 $55 $55 $55 $55 $55 $55 $55 $55 $55 $55 $55 $55 $55 $55 $55 $55 $55 $55 $55 $55
$55 = 01010101
To load the pa‘ern in the system, use the GPLoad command.
To load this parDcu- lar pa‘ern into Group 2 and Buffer 1, the command would be:
display 1b 2b 02 01 00 20 00 08 00 20 55 55 … 55
32 Dmes
number
of
bytes
(32)
y
size
of
pa‘ern
(8)
x size
of
pa‘ern
(32)
buffer number
group number
GPLoad command
• When making a pa‘ern using four colors, a pixel is made up of two bits instead of one.
This means that the pa‘ern consists of 64 bytes instead of 32.
The diagram below shows the bit set pa‘ern for the same verDcal pa‘ern using 4 colors:
1100110011001100110011001100110011001100110011001100110011001100 1100110011001100110011001100110011001100110011001100110011001100 1100110011001100110011001100110011001100110011001100110011001100 1100110011001100110011001100110011001100110011001100110011001100 1100110011001100110011001100110011001100110011001100110011001100 1100110011001100110011001100110011001100110011001100110011001100 1100110011001100110011001100110011001100110011001100110011001100 1100110011001100110011001100110011001100110011001100110011001100
44
When the binary for the 4×8 pixel data is compressed into byte data, noDce that each row consists of 8 bytes of data.
The pa‘ern now looks like this:
$CC $CC $CC $CC $CC $CC $CC $CC $CC $CC $CC $CC $CC $CC $CC $CC $CC $CC $CC $CC $CC $CC $CC $CC $CC $CC $CC $CC $CC $CC $CC $CC $CC $CC $CC $CC $CC $CC $CC $CC $CC $CC $CC $CC $CC $CC $CC $CC $CC $CC $CC $CC $CC $CC $CC $CC $CC $CC $CC $CC $CC $CC $CC $CC
$CC = 11001100
To load the pa‘ern in the system, use the GPLoad command as described for the 2 color example, but specify $40 (64) bytes instead of $20 (32).
• When making a pa‘ern using 16 colors, a pixel is made up of four bits instead of
one.
This means that the pa‘ern consists of 128 bytes.
Each line in the bit pa‘ern would look like this:
11110000…(repeat pa‘ern for 16 total sets)…11110000
When the binary for the 8×8 pixel data is compressed into byte data, the pa‘ern is a series of $F0.
To load the pa‘ern in the system, use the GPLoad command and specify $80 (128) bytes as the size.
• Please see the FFill secDon for some special notes that pertain to it when using
pa‘erns.
45
PutBlk Put Block
Code: 1B 2D
Notes:
FuncLon: Moves a GET/PUT buffer, previously copied from the screen or loaded with GPLoad, to an area of the screen.
Parameters: GRP BFN HBX LBX HBY LBY
HBX/LBX = x-locaGon of block (upper lew corner) HBY/LBY = y-locaGon of block
• The dimensions of the block were saved in the GET/PUT buffer when you created
it.
NitrOS-9 uses these dimensions when restoring the buffer.
• The screen type conversion is automaDcally handled by the PutBlk rouDne in the driver.
Please note that PutBlk will slow down noDceably if screen type conversion is required.
• GET/PUT buffers cannot be scaled.
The image will be clipped if it does not fit
• If PutBlk’s X coordinates are byte aligned with the original GetBlk, the PutBlk is
within the window.
much faster.
46
ScaleSw Scale Switch
Code: 1B 35
Parameters: BSW
Notes:
a figure and text.
coordinates:
Scaling enabled:
FuncLon: Disables and enables automaDc scaling.
Normally, automaDc scaling is en- abled.
When scaling is enabled, coordinates refer to a relaDve locaDon in a window that is proporDonate to the size of the window.
When scaling is disabled, coordinates passed to a command will be the actual coordinates for that type of screen relaDve to the origin of the window.
BSW = switch 00 = off 01 = on (Default)
• A useful applicaDon of disabled scaling is the arrangement of references between
• All coordinates are relaDve to the window's origin (0,0).
The valid range for the
y = 0-199 for 25 line screens
0-191 for 24 lines or less screens
x = 0-639
Scaling disabled:
y = 0-size of y - 1 x = 0-size of x - 1
47
FuncLon: Causes the current process's window to become the acDve (display) window.
You can select a different window by using the form:
display 1B 21>/wnumber
where number is the desired window number.
If the process that executes the select is running on the current interacDve (input/display) window, the selected window be- comes the interacDve window, and the other window becomes passive.
Select Window Select
Code: 1B 21
Parameters: None
Notes:
• The keyboard is a‘ached to the process's selected window through the use of the
key.
This lets you input data from the keyboard to different windows by CLEAR using the key to select the window.
All display windows that occupy the same screen are also displayed.
CLEAR
• The device window that owns the keyboard is the current interacDve window.
The interacDve window is always the window being displayed.
Only one process may receive input from the keyboard at a Dme.
Many processes may be changing the output informaDon on their own windows; however, you can only see the infor- maDon that is displayed on the interacDve window and any other window on the same screen as the interacDve window.
48
TCharSw Transparent Character Switch
FuncLon: Defines the character mode to be used when puong characters on the graph- ics screens.
In the default mode (transparent off), the system uses block characters that draw the enDre foreground and background for that cell.
When in transparent mode, the only pixels that are changed are the ones where the character actually has pixels set in its font.
When transparent mode is off, all pixels in the character block are set: foreground or font pixels in the foreground color and others in the background color.
NitrOS-9 EOU Beta 2 and up specific:
Now works on hardware text screens.
This will allow you to change
the foreground color, underline and blink a‘ributes while leaving the background color alone.
Code: 1B 3C
Parameters: BSW
BSW = switch
00 = off (Default) 01 = on
49
Chapter 4.
Drawing Commands
All drawing commands relate to an invisible point of reference on the screen called the draw pointer.
Originally, the draw pointer is at posiDon 0,0.
You can change the posiDon by using the SetDPtr and RSetDPtr commands described in this chapter.
In addiDon, some draw commands automaDcally update the draw pointer.
For example, the LineM command draws a line from the current draw pointer posiDon to the specified end coordinates and moves the draw pointer to those end coordinates.
The Line command draws a line but does not move the pointer.
Also, note that all draw commands are affected by the pa‘ern and logic commands described in Chapter 3.
Do not confuse the draw pointer with the graphics cursor.
The graphics cursor is the graphic representaDon of the mouse/joysDck posiDon on the screen.
An opDmizaDon note on all the Line commands – horizontal and verDcal lines draw much faster than diagonal lines.
An opDmizaDon note when using fonts: Since fonts are naDvely stored as two color bit- maps (one bit per pixel), the corresponding graphical screen type (Type 5) will render text the fastest.
If you do not require mulDple colors, but want either mulDple fonts and/or single color graphics on the screen simultaneously, this mode will render text much faster (and take less RAM).
In this chapter, commands that use relaDve coordinates (offsets) are listed with their counterparts that use absolute coordinates.
For example, RSetDPtr is listed with Set- DPtr.
50
Arc3P Draw Arc
Code: 1B 52
Notes:
FuncLon: Draws an arc with its midpoint at the current draw pointer posiDon.
You spec- ify the curve by both the X and Y dimensions, as you do an ellipse.
In this way, you can draw either ellipDcal or circular arcs.
The arc is clipped by a line defined by the (X01,Y01) - (X02,Y02) coordinates.
These coordinates are signed 16 bit values and are relaDve to the center of the ellipse.
The draw pointer remains in its original posiDon.
Parameters: HBRx LBRx HBRy LBRy HX01 LX01 HY01 LY01 HX02 LX02 HY02 LY02
• The resulDng arc depends on the order in which you specify the line coordinates.
Arc3P first draws the line from Point 1 to Point 2 and then draws the ellipse in a clockwise direcDon.
• The coordinates of the screen are as follows:
-X
+X
-Y
+Y
51
FuncLon: Draws and fills a rectangle that is defined by the diagonal line from the cur- rent draw pointer posiDon to the specified posiDon.
The box is drawn in the current foreground color.
The draw pointer returns to its original locaDon.
Bar Draw Bar
Code: 1B 4A
RBar
Parameters: HBX LBX HBY LBY
RelaDve Draw Bar
FuncLon: Draws and fills a rectangle that is defined by the diagonal line from the cur- rent draw pointer to the point specified by the offsets.
The box is drawn in the current foreground color.
The draw pointer returns to its original locaDon.
This is a relaDve com- mand.
Code: 1B 4B
Parameters: HBXo LBXo HBYo LBYo
52
FuncLon: Draws and fills a rectangle that is defined by the diagonal line from the cur- rent draw pointer posiDon to the specified posiDon.
The box is drawn in the current foreground color.
The draw pointer returns to its original locaDon.
Box Draw Box
Code: 1B 48
Parameters: HBX LBX HBY LBY
RBox RelaDve Draw Box
FuncLon: Draws and fills a rectangle that is defined by the diagonal line from the cur- rent draw pointer point specified by the offsets.
The box is drawn in the current fore- ground color.
The draw pointer returns to its original locaDon.
This is a relaDve com- mand.
Code: 1B 48/1B 49
Parameters: HBX LBX HBY LBY/HBXo LBXo HBYo LBYo
53
Circle Draw Circle
Code: 1B 50
Parameters: HBR LBR
FuncLon: Draws a circle of the specified radius with the center of the circle at the cur- rent draw pointer posiDon.
The circle is drawn in the current foreground color.
The draw pointer remains in its original locaDon.
54
Ellipse Draw Ellipse
FuncLon: Draws an ellipse with its center at the current draw pointer posiDon.
The X value specifies the horizontal radius, and the Y value specifies the verDcal radius.
The el- lipse is drawn in the current foreground color.
The draw pointer remains in its original locaDon.
This is a relaDve command.
Code: 1B 51
Parameters: HBRx LBRx HBRy LBRy
55
FFill Flood Fill
Code: 1B 4F
Parameters: None
FuncLon: Fills the area where the background is the same color as the draw pointer.
Fill- ing starts at the current draw pointer posiDon, using the current foreground color.
The draw pointer returns to its original locaDon.
This is a relaDve command.
Notes: Pa‘erns will generally work well with any commands that support them (like Bar, etc), but FFill is one that you have to be careful with.
Because FFill uses the stack to keep track of every single point it has to come back to carry on filling (when it hits a dif- ferent color), and there is not a ton of stack space in the Grfdrv system map, excessively complex fill areas can cause a stack overflow error.
To compound this further, because you are changing the pixel values in a non-consistent way, it has the potenDal to get stuck in an infinite loop as it never returns to the iniDal start point to finish.
We have put in special code to force it to exit if it seems to be stuck in such a loop, or gets trapped without reaching every part it should have, and there is also special code to allow FFill to try to “finish” as many paint points as it can even if a stack overflow occurs (using the points already on the stack).
The net result of all of this is that it should never com- pletely lock up the graphics driver subsystem (which previous versions could), and also that the results may not be perfect on very complex, large paint areas.
As a program- mer/developer, to avoid such issues, some guidelines/Dps to note:
1) Try and make sure that FFill's with pa‘erns are always in small confined areas.
If you want a whole background to be a pa‘ern, with a bunch of smaller objects/drawing done as well, do a Bar with pa‘ern first instead, and THEN draw your addiDonal objects/ shapes.
I have encountered no issues with small, or larger non-complex, shapes to FFill in.
2) Add an error trap so that you can handle the Stack Overflow error, if you can't fix things with point 1) above.
Please note that someDmes it may complete the FFill cor- rectly even with the error; it depends on what points were saved and what their sur- roundings were like.
But someDmes it won't complete everything properly, either.
56
3) Use other drawing commands with Pa‘erns instead.
All others (Bar, Box, Filled Circle, Filled Ellipse, etc.) are fixed areas of the screen, and thus don't potenDally “leak” into other areas.
FFill is the only command that can, so it should be used only when abso- lutely necessary.
4) FFill's with plain colors and no pa‘erns can sDll potenDally create a stack overflow er- ror if it is a hugely complex paint area, but it is much rarer than with a pa‘ern (once an area is filled, it becomes “off limits” to the boundary checking, and thus doesn't loop back trying to repaint areas that it has already done).
57
FCircle Draw filled circle
Code: 1B 53
Parameters: HBR LBR
FuncLon: Draws a filled circle of the specified radius with the center of the circle at the current draw pointer posiDon.
The filled circle is drawn in the current foreground color.
The draw pointer remains in its original locaDon.
58
FEllipse Draw Filled Ellipse
FuncLon: Draws an filled ellipse with its center at the current draw pointer posiDon.
The X value specifies the horizontal radius, and the Y value specifies the verDcal radius.
The filled ellipse is drawn in the current foreground color.
The draw pointer remains in its original locaDon.
This is a relaDve command.
Code: 1B 54
Parameters: HBRx LBRx HBRy LBRy
59
FuncLon: Draws a line from the current draw pointer posiDon to the specified point, us- ing the current foreground color.
The draw pointer returns to its original locaDon.
Line Draw Line
Code: 1B 44
Parameters: HBX LBX HBY LBY
Rline RelaDve Draw Line
FuncLon: Draws a line from the current draw pointer posiDon to the point specified by the x,y offsets, using the current foreground color.
The draw pointer returns to its origi- nal locaDon.
This is a relaDve command.
Code: 1B 45
Parameters: HBXo LBXo HBYo LBYo
60
FuncLon: Draws a line from the current draw pointer posiDon to the specified point, us- ing the current foreground color.
The draw pointer stays at the new locaDon.
LineM Draw Line and Move
Code: 1B 46
Parameters: HBX LBX HBY LBY
RLineM RelaDve Draw Line and Move
FuncLon: Draws a line from the current draw pointer posiDon to the point specified by the offsets, using the current foreground color.
The draw pointer stays at the new loca- Don.
This is a relaDve command.
Code: 1B 47
Parameters: HBXo LBXo HBYo LBYo
61
Point Draw Point
Code: 1B 42
Parameters: HBX LBX HBY LBY
RPoint RelaDve Draw Point
Code: 1B 43
Parameters: HBXo LBXo HBYo LBYo
FuncLon: Draws a pixel at the specified coordinates, using the current foreground color.
FuncLon: Draws a pixel at the locaDon specified by the offsets, using the current fore- ground color.
This is a relaDve command.
62
PutGC Put Graphics Cursor
Code: 1B 4E
Parameters: HBX LBX HBY LBY
FuncLon: Puts and displays the graphics cursor at the specified locaDon.
The coordi- nates passed to this command are not window relaDve.
The horizontal range is 0 to 639.
The verDcal range is 0 to 191.
The default posiDon is 0,0.
This command is useful for applicaDons running under CoGrf (or CoWin) so that you can display a graphics cursor even if you don't want mouse control of the cursor.
63
FuncLon: Sets the draw pointer to the specified coordinates.
The new draw pointer po- siDon is used as the beginning point in the next draw command if other coordinates are not specified.
FuncLon: Sets the draw pointer to the specified in the offsets.
The new draw pointer po- siDon is used as the beginning point in the next draw command if other coordinates are not specified.
This is a relaDve command.
SetDPtr Set Draw Pointer
Code: 1B 40
Parameters: HBX LBX HBY LBY
RSetDPtr RelaDve Set Draw Pointer
Code: 1B 41
Parameters: HBXo LBXo HBYo LBYo
64
Chapter 5.
Text Commands
The text commands let you control the cursor's posiDon and movement and also the way text prints on the display.
These commands can be used on either text or graphics windows.
Code
DescripLon
01 02
03 04 05 20 05 21 06 07 08 09 0A 0B 0C 0D 1F 20 1F 21 1F 22 1F 23 1F 24 1F 25 1F 30 1F 31 1B 3C BSW 1B 3D BSW 1B 3F BSW
Homes the cursor.
PosiDons cursor to X/Y.
Specify coordinates as (x + $20) and (y + $20).
Erases the current line.
Erases from the current character to the end of the line.
Turns off the cursor.
Turns on the cursor.
Moves the cursor right one character.
Rings the bell.
Moves the cursor lew one character.
Moves the cursor up one line.
Moves the cursor down one line.
Erases from the current character to the end of the screen.
Erases the enDre screen and homes the cursor.
Sends a carriage return.
Turns on reverse video Turns off reverse video Turns on underlining.
Turns off underlining.
Turns on blinking.
Turns off blinking.4 Inserts a line at the current cursor posiDon.
Deletes the current line.
See TCharSw5 See BoldSw in Chapter 36 See PropSw in Chapter 36
4 Blink is not supported for text on graphics screens.
5 See TCharSw descripDon for how this works between hardware text and graphics
screens.
6 These characterisDcs are supported for text on graphics screens only.
65
The NitrOS-9 EOU Level 2 Windowing System Manual
OpLmizaLon Tips:
Some notes on how to get the best performance from your programs that are using the Grfdrv based graphics system:
1) Window scrolling, GetBlk/PutBlk's on byte aligned boundaries, horizontal lines, boxes, bars and Flood fills have been opDmized so that larger widths of these will run faster than previous versions (including EOU Beta 5).
The absolute opDmum condiDon for the greatest gain in speed is on even 8 byte boundaries (so every 4 characters on a hardware text screen, and every 16 pixels on 16 color screens, every 32 pixels on 4 color screens, and every 64 pixels on 2 color screens), and in even mulDples of 8 bytes in width.
But anything >=8 bytes wide should be faster than before, and <8 bytes wide is only marginally slower.
2) For scrolling in parDcular, windows that are the full width of the screen will scroll slightly faster than windows that are not the full width of the screen, irregardless of height.
This is more noDceable on the 6309 versions of NitrOS-9, but also affects the 6809 versions as well.
3) 8 pixel wide fonts are opDmized to run faster than 6 pixel wide fonts, or when the pro- porLonal a‘ribute is turned on.
Like up to several Dmes faster.
4) Using a font that is pre-bolded in the font itself, it slightly faster at prinDng than pick- ing a normal font and turning the Bold a‘ribute on.
5) PutBlk’s that end up running off the bo‘om of the window are opDmized to not slow down (actually, they speed up), which is good for certain effects.
We plan on expanding this funcDonality to the other 3 sides of a window in the future, but through EOU Beta 6, it is currently only opDmized on the bo‘om.
66
The NitrOS-9 EOU Level 2 Windowing System Manual
AlphabeLcal Index
Arc3P…………………………………………………………………………………………………….50 Bar………………………………………………………………………………………………………..51 BoldSw……………………………………………………………………………………………..15, 63 Border…………………………………………………………………………………………16, 24, 39 box……………………………………………………………………………………………………..51p.
Box………………………………………………………………………………………………………..52 circle………………………………………………………………………………………………..53, 56 Circle……………………………………………………………………………………………………..53 CWArea…………………………………………………………………………………………………17 DefColr…………………………………………………………………………………………………..18 device window……………………………………………………………..6, 9, 22pp., 36pp., 47 Device Window……………………………………………………………………………….6, 22pp.
DfnGPBuf……………………………………………………………………………………………….19 DWEnd………………………………………………………………………………………………….22 DWProtSw……………………………………………………………………………………………..23 DWSet…………………………………………………………………………………….6p., 17, 24p.
ellipse………………………………………………………………………………………….50, 54, 57 Ellipse………………………………………………………………………………………………54, 57 FCircle…………………………………………………………………………………………………..56 FColor……………………………………………………………………………………………………26 FFill……………………………………………………………………………………………………….55 fill…………………………………………………………………………………………10 Fill…………………………………………………………………………………………………………55 font…………………………………………………………10p., 15, 20p., 24, 27pp., 32, 41, 48 Font…………………………………………………………………………………………….24, 27, 32 GCSet……………………………………………………………………………………………………30 GetBlk……………………………………………………………………………………………………31 GPLoad……………………………………………………………………………..21, 27, 32, 43pp.
GrfDrv……………………………………………………………………………………………………..5 GrfInt………………………………………………………………………………………………….5, 61 KilBuf………………………………………………………………………………………….19, 31, 33 line………………………………………………………..7, 20, 25, 27, 44, 46, 49pp., 58p., 63 Line……………………………………………………………………………………………….49, 58p.
LineM……………………………………………………………………………………………….49, 59 LSet……………………………………………………………………………………………………34p.
overlay window……………………………………………………………………………9, 17, 36p.
Overlay Window………………………………………………………………………………..9, 36p.
OWEnd……………………………………………………………………………………………….36p.
OWSet………………………………………………………………………………………….9, 17, 37 Palette………………………………………………………………………14, 16, 18, 25p., 35, 39 Point…………………………………………………………………………………………………50, 60 PropSw……………………………………………………………………………………….27, 41, 63
67
The NitrOS-9 EOU Level 2 Windowing System Manual
PSet………………………………………………………………………………………………………42 PutBlk……………………………………………………………………………………………31p., 45 PutGC……………………………………………………………………………………………………61 RBar………………………………………………………………………………………………………51 RBox……………………………………………………………………………………………………..52 Relative Draw Box…………………………………………………………………………………..52 Relative Draw Line…………………………………………………………………………………..58 Relative Draw Line and Move……………………………………………………………………59 Relative Draw Point…………………………………………………………………………………60 Relative Set Draw Pointer…………………………………………………………………………62 Rline………………………………………………………………………………………………………58 RLineM………………………………………………………………………………………………….59 RPoint……………………………………………………………………………………………………60 RSetDPtr…………………………………………………………………………………………..49, 62 ScaleSw…………………………………………………………………………………………………46 Select……………………………………………………………………………………………….27, 47 SetDPtr…………………………………………………………………………………………….49, 62 system……………………………………………………..5, 17pp., 30, 32p., 37, 40, 43p., 48 System………………………………………………………………………………………1, 5, 10, 18 TCharSw………………………………………………………………………………………………..48 WindInt…………………………………………………………………………………………………….5
68
Return to Top or NitrOS9EOU