The <wingraph.h> header file
This header file contains the following functions:
DrawStaticButton DrawWinBorder MakeWinRect RectWinToScr
RectWinToWin WinActivate WinAttr WinBackground
WinBackupToScr WinBegin WinBitmapGet WinBitmapPut
WinBitmapSize WinChar WinCharXY WinClose
WinClr WinDeactivate WinDupStat WinEllipse
WinEnd WinFill WinFillLines2 WinFillTriangle
WinFont WinGetCursor WinHeight WinHide
WinHome WinLine WinLineNC WinLineRel
WinLineTo WinMoveCursor WinMoveRel WinMoveTo
WinOpen WinPixGet WinPixSet WinRect
WinReOpen WinScrollH WinScrollV WinSetCursor
WinShow WinStr WinStrXY WinWidth
the following global variables:
DeskTop FirstWindow
and the following constants and predefined types:
Attrs Bool BoxAttrs BITMAP
BITMAP_HDR_SIZE Buttons Fonts ICON
NULL pICON SCR_COORDS SCR_RECT
WIN_COORDS WIN_RECT WINDOW WinFlags
Functions
short WinOpen (WINDOW *w, const WIN_RECT *rect, unsigned short Flags, ...);
Opens a new window.
WinOpen opens a new window, initializing all fields of the
WINDOW structure pointed to by w, then links this window into the
current list of windows as the topmost window. rect is the pointer
to the rectangular structure of type WIN_RECT which defines the
window area. The Flags may be
set as one or more (ORed) following constants defined in enum WinFlags
(WF_SAVE_SCR and WF_DUP_SCR are mutually exclusive):
WF_SAVE_SCR |
Save the screen region underneath the window (restore it when the window is closed) |
WF_DUP_SCR |
Keep a duplicate copy of all data written to the window; when the window needs to be
updated, the application will not receive a CM_WPAINT message, instead the system will update
the window (see EV_paintOneWindow for more info)
|
WF_TTY |
Write characters in TTY mode (translate '\n' and '\r' to a newline, '\f' to clear screen, and wrap
at end of lines) |
WF_NOBOLD |
When window is activated, do not BOLD the window's border |
WF_NOBORDER |
Do not draw border for window |
WF_ROUNDEDBORDER |
Draw a rounded border instead of rectangular border (this option imply WF_NOBOLD too) |
WF_TITLE |
Draw a title bar; Flags parameter in this case must be followed by a text string
which will be used as the window title (in according to my experience, it seems that only
windows with rounded border may have a title bar) |
WF_VIRTUAL |
Set this flag for non-real virtual windows which are just allocated
bitmaps in the memory and which are not limited to the size of the screen;
no writes to actual LCD are done but only writes to a duplicate screen area
(so WF_DUP_SCR must also be set)
|
WinOpen returns FALSE if there is not enough memory to
allocate save buffer, else returns TRUE. Here is one example
which displays "Hello world!" in a window (assuming that there was no errors):
WINDOW w;
WinOpen (&w, MakeWinRect (20, 20, 120, 50), WF_SAVE_SCR | WF_TTY));
WinActivate (&w);
WinFont (&w, F_6x8);
WinStr (&w, "Hello world!");
ngetchx ();
WinClose (&w);
Like any other function which allocates a memory block, WinOpen may cause the
heap compression.
NOTE: You must call WinActivate to display a window to the screen,
although TI said that you do not need to do so. Also, don't forget to CLOSE all windows
(using WinClose) before the end of the program, else the TI will
crash later, when TIOS window manager wound try to refresh window in the list which ceased
to exist after terminating the program!
void WinActivate (WINDOW *w);
Activates a window.
WinActivate makes the window pointed to by w the current active window.
This will cause the following events:
-
The currently active window will be deactivated (its border will be changed to a single-line
border);
- The border for the window will switch to a double-line border (except in single-border
mode, in rounded-border mode or if the window is a full-screen window);
- The graphics system will be reset to the current windows defaults (draw attributes, current
(x, y) location, etc.).
- The window will be marked as visible (see WinHide).
See WinOpen for more info.
NOTE: Because of memory requirements, only the active window may be drawn to. Once a window
becomes the active window, it may use any of the window drawing routines. If you try to draw
in a non-active window, a garbage may appear on the screen. If no other window overlaps a
window (even if there are multiple windows on the screen), then you may write to a non-active
window by using WinBegin and WinEnd to bracket
the writes.
void WinDeactivate (WINDOW *w);
Deactivates a window.
WinDeactivate deactivates a window pointed to by w. In fact, it only changes its border
to the single-line border, without giving a focus to any other window. It is really only needed
if an application has multiple windows. The purpose is to provide a visual clue to the user that
a particular window has lost the current focus and that another window (which will be activated
with WinActivate) has received the focus. When
WinActivate is called, the window with the current focus (the last
one to do an activating) is automatically deactivated with WinDeactivate and so it is not
necessary to explicitly call WinDeactivate.
void WinHide (WINDOW *w);
Hides a window.
WinHide hides a window pointed to by w (mark it as not-visible so that it is never
activated by the system) and updates the screen. When a window is activated
(see WinActivate) or when it is opened (unless the
WF_VIRTUAL flag is passed to WinOpen), it is
marked as visible. All windows in the system are kept in a linked list. When a window in the
system is closed, the next visible window in the system is activated and becomes the currently
active window. Since virtual windows are never displayed on the screen they are never considered
visible. An application's main window is always visible since that is the only view the user has
of the application. From the other side, an application may open other windows that it does not
want to ever be activated. In that case, use WinHide so that they will never be activated by
the system. Although the given window will not be activated by the system, writes to it still
go to the screen (unless it is a virtual window).
void WinClose (WINDOW *w);
Closes a window.
WinClose closes a window pointed to by w, releasing any memory assigned to it and
activating the next window in the window-list. This may mean redrawing portions of
the screen in order to keep it up-to-date.
short WinReOpen (WINDOW *w, const WIN_RECT *rect, unsigned short Flags, ...);
Reopens an existing window.
WinReOpen acts like WinOpen, but reopens an existing window. Not valid
for windows created in WF_SAVE_SCR mode (unless using just to call
WinOpen). If the window is not in the "list of windows" then just
calls WinOpen. Otherwise, it updates the Client, Window, Clip, and Port
regions of the window. If the new window is of the same size as the old one, then the Port
region (DUP_SCR) is not cleared. Returns TRUE if the window re-opened OK,
and returns FALSE if not (bad window or not enough memory to enlarge
DUP_SCR).
NOTE: This is the official information by Texas Instruments. I am not sure that I fully
understood what they want to say. It seems that you can reopen a window on a new place
(keeping the same size), then redraw the window on a new position using
WinBackupToScr.
void WinBegin (WINDOW *w);
Setup a window for writing to without activating the window.
WinBegin setup the window pointed to by w for writing to it without activating it.
When writing to the window is done, call WinEnd. See
WinActivate for more info.
void WinEnd (WINDOW *w);
Ends writing to a non-active window.
If you write to a non-active window, then bracket the writes with
WinBegin and WinEnd.
See WinActivate for more info.
short WinDupStat (WINDOW *w, short Stat);
Turns the duplicate status on or off.
WinDupStat turn the duplicate status of the window pointed to by w on
(Stat = TRUE) or off
(Stat = FALSE). When the duplicate status is
turned off, all writes to a window go only to the screen. When turned on, all writes
go to both the screen and the backup window. This only applies to windows created with
the WF_DUP_SCR flag set. See WinOpen for
more info. Beware that duplicate writes slow down all writes to windows with
WF_DUP_SCR flag set. WinDupStat also returns the previous
duplicate writing status.
NOTE: This is an official information from TI. I must admit that many things about
window management (especially about overlapping windows) is still very obscure to me.
short WinWidth (WINDOW *w);
Width of a window.
WinWidth returns the width of the client (drawable) area of the window pointed to by w.
The window region is the region that was defined when the window was
created with WinOpen. If the window is full screen (not counting
the status bar which may not be overlapped), then the client region is equal to the
window region. The client region is reduced by adding borders or a title to a window.
short WinHeight (WINDOW *w);
Height of a window.
WinHeight returns the height of the client (drawable) area of the window pointed to by
w. The window region is the region that was defined when the window was
created with WinOpen. If the window is full screen (not counting
the status bar which may not be overlapped), then the client region is equal to the
window region. The client region is reduced by adding borders or a title to a window.
short WinAttr (WINDOW *w, short Attr);
Sets the default window attribute.
WinAttr sets the attribute for the next write (or draw) to the window pointed to by w
to Attr. This attribute will be used in all drawing commands which have not an
attribute as explicite parameter. The interpretation of the attribute depends of concrete
graphic command. Some attributes are only valid for certain graphic operation. Legal attribute
values are defined in enum Attrs. In a general, the following attributes
are supported:
A_REVERSE | Destination pixels turned off |
A_NORMAL | Destination pixels turned on |
A_XOR | Source pixels XORed with destination pixels |
A_SHADED | Destination pixels masked so that every other pixel turned off |
A_REPLACE | Source pixels replace destination pixels |
A_OR | Source pixels ORed with destination pixels |
For lines the following additional attributes are supported:
A_THICK1 | Draw a double thick line |
A_SHADE_V | Draw the line using a vertical shading pattern |
A_SHADE_H | Draw the line using a horizontal shading pattern |
A_SHADE_NS | Draw the line using a negative slope diagonal shading pattern |
A_SHADE_PS | Draw the line using a positive slope diagonal shading pattern |
WinAttr returns the previous current attribute.
NOTE: Although TI said nothing about it, attributes A_SHADE_V, A_SHADE_H, A_SHADE_NS and
A_SHADE_PS work only for lines with slope more than 45 degree (i.e. for lines which are
more "vertical" than "horizontal"). For "nearly horizontal" lines all of them act like
A_NORMAL. I don't know whether it is a bug, or planned feature. So, if you want to draw
shaded-fill rectangle using a line drawing command (for example, WinLine)
in a loop, use vertical lines for drawing, not horizontal ones! Note also that these additional
attributes work fine with WinFillTriangle and
WinFillLines2, but not with WinFill!
void WinBackground (WINDOW *w, short Attr);
Sets the default window background.
WinBackground changes the current default attribute for the background of a window
pointed to by w (used to clear the window using WinClr).
Note that the background attribute is also used to fill up a newly created area when
a window content is scrolled in any direction. Valid values for Attr are:
A_NORMAL | Black background |
A_REVERSE | White background |
A_XOR | All pixels will be reversed during clearing |
See WinAttr for more info about attributes.
NOTE: TI said that attribute A_SHADED (set to a pattern of pixels on and off) is also supported,
but it didn't work when I tried it; at least, it does not work on AMS 1.00.
void WinClr (WINDOW *w);
Clears a window.
WinClr clears the client area (i.e. area without the border and without the optional
title bar) of the window pointed to by w (using the current clip region), and
resets the current (x, y) position to the home of the client region. The current
background pattern (set using WinBackground)
is used to fill the client area.
void WinFont (WINDOW *w, short Font);
Sets the current window font.
WinFont changes the current text font for the window pointed to by w. All subsequent
characters written to the window will use this font. The supported values for Font
are F_4x6, F_6x8, and F_8x10, and they are defined in enum Fonts.
The 4x6 font is a proportional font while the 6x8 and 8x10 fonts are fixed-width.
void WinMoveTo (WINDOW *w, short x, short y);
Sets the current window pen position.
WinMoveTo sets the current pen position for the window pointed to by w to
(x, y). The coordinates are relative to the topleft corner of the window.
WinMoveTo affects where WinChar and WinStr draw
characters and strings as well as the line position for WinLineRel
and WinLineTo.
void WinMoveRel (WINDOW *w, short dx, short dy);
Sets the current window pen position relative to the current pen position.
WinMoveRel acts like WinMove, but dx and dy
are relative to the current pen position.
void WinLineTo (WINDOW *w, short x, short y);
Draws a line to a window from the current pen position.
WinLineTo draws a line to the window pointed to by w from the current pen position to
the pixel (x, y) using the current attribute given with
WinAttr command, then updates the pen position to those coordinates.
The current pen position can be initialized with WinMoveTo.
Note that the coordinates are relative to the topleft corner of the window.
The line will be clipped at the boundaries of the window clipping area. Here is a list of
the supported attributes:
A_NORMAL | Draw a normal line |
A_REVERSE | Draw an inverse line (i.e. erase the line) |
A_XOR | Draw a line using XORing with the destination |
A_THICK1 | Draw a double thick line |
A_SHADE_V | Draw the line using a vertical shading pattern |
A_SHADE_H | Draw the line using a horizontal shading pattern |
A_SHADE_NS | Draw the line using a negative slope diagonal shading pattern |
A_SHADE_PS | Draw the line using a positive slope diagonal shading pattern |
See WinAttr command for a more general info about attributes.
Note that although TI said nothing about it, attributes A_SHADE_V, A_SHADE_H, A_SHADE_NS
and A_SHADE_PS work only for lines with slope more than 45 degree (i.e. for lines which
are more "vertical" than "horizontal"). For "nearly horizontal" lines all of them act
like A_NORMAL. I don't know whether it is a bug, or planned feature. So, if you want to
draw shaded-fill rectangle using WinLine in a loop, use vertical lines for drawing, not
horizontal ones!
void WinLineRel (WINDOW *w, short dx, short dy);
Draws a line to a window from the current pen position, using relative displacements.
WinLineRel acts like WinLine, but dx and dy
are relative to the current pen position.
void WinChar (WINDOW *w, char c);
Draws a character to a window.
DrawChar writes a character c at the current (x, y) location of the window
pointed to by w, using the current window attribute (set using WinAttr).
The character will be clipped at the boundaries of the window clipping area. The following
character attributes are supported (the region defined by a character is 8x10
for huge font, 6x8 for large font or nx5 for small font, depending on the
current font set by WinFont command):
A_NORMAL | The character is ORed into the destination |
A_REVERSE | The region created by inversing the character replaces the destination |
A_REPLACE | The region defined by the character replaces the destination |
A_XOR | The character is XORed into the destination |
A_SHADED | The character masked so that every other pixel is turned off then ORed into the destination |
See WinAttr command for a more general info about attributes.
NOTE: If the window is opened in TTY mode (see WinOpen), the current printing
location will be updated, and newline ('\n' or '\r') and formfeed ('\f') characters will be
handled correctly.
void WinCharXY (WINDOW *w, short x, short y, char c, short Count);
Draws a series of characters to a window at the specific location.
DrawCharXY writes a Count number of character c to a window pointed to by
w at a specific (x, y) location (the coordinates are relative
to the topleft corner of the window). The current (x, y) location is updated it the
wintow is in TTY mode (see WinOpen for more description about window modes).
See WinChar for more info about drawing characters.
void WinStr (WINDOW *w, const char *str);
Draws a string to a window.
WinStr draws the string str to the window pointed to by w at the current pen
location. The current pen location is updated to point to the end of where the string was
written if the window is in TTY mode (see WinOpen for more description
about window modes). See WinChar routine for a description of character
attributes and fonts.
void WinStrXY (WINDOW *w, short x, short y, const char *str);
Draws a string to a window at a specific location.
WinStrXY draws the string str to a window pointed to by w at the specific
(x, y) location (the coordinates are relative to the topleft corner
of the window). See WinStr for more info.
void WinHome (WINDOW *w);
Moves the pen location for a window to the home position
WinHome moves the pen location for the window pointed to by w to the home position.
Note that in TTY mode this is (1 1) otherwise it is (0, 0). See
WinOpen for more info about window modes.
void WinPixSet (WINDOW *w, short x, short y);
Sets a pixel in a window.
WinPixSet set a pixel at (x, y) in the window pointed to by w
using the current window attribute (set using WinAttr). The coordinates
are relative to the topleft corner of the window (the pixel will not be drawn if the coordinates
are out of the window). The following attributes are supported:
A_NORMAL | Draw a pixel |
A_REVERSE | Erase a pixel |
A_XOR | Invert a pixel |
short WinPixGet (WINDOW *w, short x, short y);
Gets the status of a pixel in a window.
WinPixGet gets the status of the pixel located at (x, y), where
coordinates are relative to the topleft corner of the window. Returns TRUE or
FALSE depending of whether corresponding pixel is set or reset.
Also returns FALSE if coordinates are outside current window.
WIN_RECT *MakeWinRect (short x0, short y0, short x1, short y1);
Builds a structure for representing rectangular area.
MakeWinRect accepts coordinates of two corners (x0, y0) and (x1, y1)
of an rectangular area, and returns the pointer to the structure of type
WIN_RECT in which these coordinates are embeded. This function may be
useful in combination with a rich set of TIOS functions which expect a structure of type
WIN_RECT as explicite argument, like
WinOpen, WinLine, etc.
NOTE: This function returns a static pointer, which will be rewritten with each call. So, you
must not use it inside functions which needs more than one parameter of type
WIN_RECT like WinFillLines2 etc.
void WinLine (WINDOW *w, const WIN_RECT Line);
Draws a line to a window.
WinLine draws a line from (x0, y0) to (x1, y1) to the window pointed to by w
where coordinates (x0, y0) and (x1, y1) are given in a
WIN_RECT structure Line, using the
current attribute. The line will be clipped at the boundaries of the
window clipping area. See WinLineTo for a description of
supported atributes.
void WinLineNC (WINDOW *w, const WIN_RECT Line);
Draws a line to a window, without range checking.
WinLineNC works like WinLine except no range checking is done on the
line drawn. Use it with extreme caution as invalid lines could trash the system.
void WinRect (WINDOW *w, const WIN_RECT *rect, short Attr);
Draws a rectangle to a window.
WinRect draws a rectangle with (x0, y0) and (x1, y1) as corners
to the window pointed to by w, where coordinates (x0, y0) and (x1, y1)
are given in a WIN_RECT structure rect. All coordinates
are relative to the topleft corner of the window. The rectangle will be clipped at the
boundaries of the clipping area of the window. The interior of the rectangle remains
intact (no fill). The border lines of the rectangle will be drawn using the attribute
Attr. See WinLineTo for a description of supported line
atributes. In addition, the attribute may be ORed with one or more following constants
(which are defined in enum BoxAttrs:
B_NORMAL | Draw a normal rectangle |
B_DOUBLE | Draw a double thick rectangle |
B_ROUNDED | Draw a rectangle with rounded corners |
B_CUT | Draw a rectangle with the upper corners cut (like in toolboxes) |
NOTE: I cannot conclude which is the difference if you OR the attribute
with B_NORMAL or if you do not so. Maybe I am stupid.
void WinEllipse (WINDOW *w, short x, short y, short a, short b);
Draws an ellipse to a window.
WinEllipse draws an ellipse with centre at (x, y) and with
semiaxes a and b to the window pointed to by w. The coordinates
are relative to the topleft
corner of the window. The ellipse will be clipped at the boundaries of the clipping
area of the window. The interior of the ellipse remains intact (no fill). The ellipse
will be drawn using the current window attribute (set using WinFill).
Supported attributes are:
A_NORMAL | Draw a elipse |
A_REVERSE | Erase a ellipse |
A_XOR | XORs a ellipse into the destination |
NOTE: Set a = b to draw a circle.
void WinFill (WINDOW *w, const WIN_RECT *rect, short Attr);
Draws a filled rectangle to a window.
WinFill draws a filled rectangle (i.e. fills a rectangular region of a window)
given by WIN_RECT structure rect to the window
pointed to by w, using the attribute Attr.
All coordinates are relative to the topleft corner of the window. The rectangle will be
clipped at the boundaries of the clipping area of the window. Supported attributes are:
A_NORMAL | Fill with black pixels |
A_REVERSE | Fill with white pixels |
A_XOR | All pixels in the rectangle will be reversed |
WinFillLines2 is more complicated and slower function than WinFill,
but it supports much more attributes. See WinAttr for more info about attributes.
NOTE: TI said that attribute A_SHADED (set to a pattern of pixels on and off) is also supported,
but it didn't work when I tried it; at least, it does not work on AMS 1.00.
void WinFillTriangle (WINDOW *w, short x0, short y0, short x1, short y1, short x2, short y2, short Attr);
Draws a filled triangle to a window.
FillTriangle draws a filled triangle with vertices (x0, y0),
(x1, y1) and (x2, y2) to the window
pointed to by w, using the attribute Attr.
All coordinates are relative to the topleft corner of the window.
The triangle will be clipped at the boundaries of the clipping area of the window.
Supported attributes are:
A_NORMAL | Draws a solid fill triangle |
A_REVERSE | Draws an empty triangle (i.e. erase a triangular area) |
A_XOR | XORs a solid fill triangle into the destination |
A_SHADE_V | Draws a triangle filled using a vertical shading pattern |
A_SHADE_H | Draws a triangle filled using a horizontal shading pattern |
A_SHADE_NS | Draws a triangle filled using a negative slope diagonal shading pattern |
A_SHADE_PS | Draws a triangle filled using a positive slope diagonal shading pattern |
See WinAttr command for a more general info about attributes.
NOTE: The 3D grapher in HIDDEN SURFACE mode uses this routine to shade the
graph using A_REVERSE if the surface is visible and A_NORMAL
if it is hidden (by splitting the graph into 6-sided polygons and splitting those into
triangles).
void WinFillLines2 (WINDOW *w, const WIN_RECT *lower_line,
const WIN_RECT *upper_line, short Attr);
Draws a filled area between two lines to a window.
WinFillLines2 fills an area bounded with two lines which coordinates are given
in two WIN_RECT structures lower_line (lower bound) and
upper_line (upper bound) to the window pointed to by w.
In fact, it draws a filled polygon whose vertices are
(lower_line.x0, lower_line.y0),
(lower_line.x1, lower_line.y1),
(upper_line.x0, upper_line.y0) and
(upper_line.x1, upper_line.y1)
using the attribute Attr.
All coordinates are relative to the topleft corner of the window.
Supported attributes are the same as in command
WinFillTriangle. The drawn polygon will be clipped at the
boundaries of the clipping area of the window. If lower_line is above
upper_line, nothing will be drawn.
To be more precise, "above" means "closer to the top of the screen".
short WinBitmapGet (WINDOW *w, const WIN_RECT *rect, void *BitMap);
Gets a bitmap from a window.
WinBitmapGet stores a series of bytes (the size of which is defined by
WinBitmapSize) defining a bitmap for a rectangular
area (whose boundaries are given using WIN_RECT structure
rect) into a buffer pointed to by BitMap. All coordinates are relative
to the topleft corner of the window pointed to by w. Actual stored bitmap may
be smaller than area defined by rect due to clipping on the boundaries of the
clipping area of the window.
The first two words at address BitMap will contain the height and the width
(in pixels) of the rectangular area respectively (after eventual clipping), then actual
data follows. BitMap is usually a pointer to a BITMAP
structure. WinBitmapGet returns FALSE if the region defined by
rect is outside of the window, and returns TRUE if it is
partially or entirely inside the window.
short WinBitmapPut (WINDOW *w, short x, short y, void *BitMap, short Attr);
Puts a bitmap to a window.
WinBitmapPut puts a bitmap BitMap (which was taken using BitmapGet)
to the window pointed to by w at the position (x, y), using the attribute Attr.
The coordinates are relative to the topleft corner of the window pointed to by w.
The drawn bitmap will be clipped at the boundaries of the clipping area of the window.
The following attributes are supported:
A_REPLACE | Replace the destination region with the source bitmap |
A_REVERSE | Replace the destination region with the inverse of the source bitmap |
A_XOR | Exculsive-OR the source bitmap into the destination region |
A_OR | OR the source bitmap into the destination region |
A_AND | AND the source bitmap into the destination region |
A_SHADED | Mask the source bitmap so that every other pixel is turned off and replace
the destination region with that result (the source region is left unchanged) |
See WinAttr command for a more general info about attributes.
unsigned short WinBitmapSize (WINDOW *w, const WIN_RECT *rect);
Determines a size of a bitmap (eventually clipped) in bytes.
WinBitmapSize returns the size in bytes of a bitmap for a part of rectangular area given by
parameter rect which belongs to the window pointed to by w (may be smaller than
the size of this area due to clipping). This size includes the data for the bitmap and the
header. All coordinates in rect are relative to the topleft corner of the window.
See WinBitmapGet for more info about bitmaps.
NOTE: WinBitmapSize will clip any negative coordinates to zero.
void WinScrollV (WINDOW *w, const WIN_RECT *rect, short NumRows);
Scrolls a region of a window upwards or downwards.
WinScrollV scrolls the rectangular area determined by rect of the window
pointed to by w upwards by NumRows pixels (or downwards
if NumRows < 0). The coordinates in rect are relative
to the topleft corner od the window. Blank areas (i.e. the vacant space produced after
scrolling) are filled with current background for the window (see
WinBackground).
NOTE: This command is not very fast because it is realized using
WinBitmapGet and WinBitmapPut.
void WinScrollH (WINDOW *w, const WIN_RECT *rect, short NumCols);
Shifts a region of a window left or right.
WinScrollH shifts the rectangular area determined by rect of the window
pointed to by w left by NumRows pixels (or right
if NumRows < 0). The coordinates in rect are relative
to the topleft corner od the window. Blank areas (i.e. the vacant space produced after
scrolling) are filled with current background for the window (see
WinBackground).
NOTE: This command is not very fast because it is realized using
WinBitmapGet and WinBitmapPut.
If the region to be scrolled starts on a byte boundary (left-most pixel), then the
region will scroll much faster.
void WinBackupToScr (WINDOW *w);
Shows a current backup screen.
If the window pointed to by w is active, WinBackupToScreen copies the current backup
screen (duplicate screen) to the real screen (more precise, to the client area of the
window), else does nothing. This routine assumes that a window is opened with the
WF_DUP_SCR flag (see WinOpen). Then, all output
to that window is saved in a backup screen image (allocated in the heap). So, this routine
copies the contents of that image to the real screen.
See also DrawWinBorder.
void WinMoveCursor (WINDOW *w, short x, short y);
Moves the pen position (???)
On the Texas Instruments site, TI comments related to this function are (cite):
use WinMoveTo to move pen position, use
WinSetCursor to move cursor. Obviously, I am too stupid
to conclude what is the difference between the pen position and the cursor. To be
more precise, I don't know what "cursor" means to them. I don't see any difference
between this command and WinMoveTo. Any info is welcomed.
If this fact may help, WinMoveTo changes CurX and CurY
fields of the WINDOW structure, WinMoveCursor changes both
CurX, CurY and CursorX, CursorY pairs, and WinSetCursor changes only
CursorX and CursorY field. Please help!!!
void WinSetCursor (WINDOW *w, short x, short y);
Moves the cursor (???)
See the note under WinMoveCursor. WinSetCursor
really does not produce any visible effect for me. It is a macro defined by
TI which changes CursorX and CursorY fields of the WINDOW
structure.
void WinGetCursor (WINDOW *w, short *x, short *y);
Returns the cursor location for a window.
WinGetCursor returns the cursor location for the window pointed to by w
into x and y. But, I am not quite sure what the "cursor" is.
See notes about WinMoveCursor.
void WinShow (WINDOW *w);
Makes a window visible for the repainting routine.
This is a simple macro defined by Texas Instruments. It sets WF_VISIBLE flag of the
window pointed to by w, making the window "visible" for event-driven repainting routine.
This flag is used only in event driven applications (see event.h
header file, especially EV_paintOneWindow function).
void DrawStaticButton (WINDOW *w, short ButtonType, short x);
Draws a button in a window.
DrawStaticButton draws a button at the bottom of the window pointed to by w,
where x is distance (in pixels) from the left edge of the window to the left
edge of the button. Parameter ButtonType determines the type of the button.
The set of possible types is very limited, and they are defined in enum
Buttons (any other values will cause a crash). The meanings
of these constants are:
BT_OK | Button "Enter=OK" |
BT_SAVE | Button "Enter=SAVE" |
BT_YES | Button "Enter=YES" |
BT_CANCEL | Button "Esc=CANCEL" |
BT_NO | Button "ESC=NO" |
BT_GOTO | Button "Enter=GOTO" |
NOTE: The current font (set using WinFont) must be F_4x6
before calling this function to work correctly.
void DrawWinBorder (WINDOW *w, SCR_RECT *rect);
Draws a border of a window.
DrawWinBorder is an internal function which draws a border of the window, and optionally
a title bar. The actual dimensions of the border are given in the SCR_RECT
structure rect, but all other parameters (border shape, etc.) will be picked from
the structure pointed to by w. Not very useful as a standalone function, although
may be sometimes used in combination with WinBackupToScr.
Note that you can pass &w.Window as the rect parameter.
Converts relative window coordinates to absolute coordinates.
RectWinToWin converts coordinates in the structure rect (which are assumed to be relative
to the topleft corner of the structure win_area) to the absolute screen coordinates.
The converted coordinates are stored again in sctructure pointed to by rect.
RectWinToWin returns rect back (but note that the structure pointed to by it is modified).
Converts relative to absolute coordinates then clips them to a window.
RectWinToScr first converts coordinates in the structure rect (which are assumed to be relative
to the topleft corner of the structure win_area) to the absolute screen coordinates.
Converted rectangular area is then clipped at the boundaries of the rectangular area
win_area, and coordinates of resulting rectangular area are stored to the structure
pointed to by result_area. RectWinToScr returns result_area. If converted
rectangular area does not overlap with win_area, result_area will be
undefined, and RectWinToScr returns NULL.
Constants and predefined types
WINDOW *FirstWindow;
FirstWindow is a pointer to the first window in the linked list of all created windows.
By starting from FirstWindow and tracking the Next field of a
WINDOW structure pointed to by it, it is possible to access to all
created windows (the last one is the window which Next field is equal
to NULL).
NOTE: Under normal conditions, FirstWindow points to the Home screen window, which is
defined as a window without a border, which occupies the space between the toolbar
menu and the command input line. When this is just a window which you want to use in your
program, you can pass FirstWindow as a parameter to any window routine
(although DeskTop is probably a better choice). And, by changing
a structure pointed to by FirstWindow, it is possible to make Home screen "larger" or
"smaller", or to perform similar "dirty" tricks. See
EV_registerMenu for a dirty example.
WINDOW *const DeskTop;
DeskTop is a constant static pointer (i.e. it can't be changed, but the structure pointed to by it
may be changed) which points to the desktop window. This is a window without a border which
occupies the whole screen area except the status line, but the clipping area of this window
is set to exclude the area occupied by the toolbar menu, so you can not draw over the menu
area if you use this window as a parameter to any window drawing function (except if you
changed Clip field of the structure pointed to by DeskTop manually). Usually, if you
want to use a function which expects a parameter
which is a pointer to a window structure, but if you don't want to create your own window,
you can pass DeskTop as the parameter to it (of course, if you don't need to draw something
in the menu or status line area).
Constants and predefined types
Bool is enumerated type for describing true or false values. It is defined as
enum Bool {FALSE, TRUE};
NULL is a null-pointer value, defined as (void *) 0.
Attrs is enumerated type for describing legal attribute values. It is defined as
enum Attrs {A_REVERSE, A_NORMAL, A_XOR, A_SHADED, A_REPLACE, A_OR, A_AND,
A_THICK1, A_SHADE_V, A_SHADE_H, A_SHADE_NS, A_SHADE_PS};
For more info about attributes, see WinAttr command.
BoxAttrs is enumerated type for describing addittional box attribute values. It is defined as
enum BoxAttrs {B_NORMAL=0x10, B_ROUNDED=0x20, B_DOUBLE=0x40, B_CUT=0x80};
For more info about box attributes, see WinRect command.
Fonts is enumerated type for describing legal font values. It is defined as
enum Fonts {F_4x6, F_6x8, F_8x10};
For more info about fonts, see WinFont command.
Buttons is enumerated type for describing possible button types. It is defined as
enum Buttons {BT_NONE, BT_OK, BT_SAVE, BT_YES, BT_CANCEL, BT_NO, BT_GOTO};
For more info about buttons, see DrawStaticButton command.
WinFlags is enumerated type for describing various flags which control the window
manager. These flags are used in WinOpen command. Usage of
some of them are still not very clear to me. See WinOpen
to see what I know about them (any additional info is welcomed). WinFlags is defined as
enum WinFlags {WF_SYS_ALLOC = 0x0001, WF_STEAL_MEM = 0x0002,
WF_DONT_REALLOC = 0x0004, WF_ROUNDEDBORDER = 0x0008, WF_SAVE_SCR = 0x0010,
WF_DUP_SCR = 0x0020, WF_TTY = 0x0040, WF_ACTIVE = 0x0080,
WF_NOBORDER = 0x0100, WF_NOBOLD = 0x0200, WF_DUP_ON = 0x0400,
WF_VIRTUAL = 0x0800, WF_TITLE = 0x1000, WF_DIRTY = 0x2000,
WF_TRY_SAVE_SCR = 0x4010, WF_VISIBLE = 0x8000};
WF_DIRTY and WF_VISIBLE are used in event driven applications, see EV_paintOneWindow
function.
SCR_COORDS is an alias type for defining physical screen coordinates. It is defined as
typedef unsigned char SCR_COORDS;
WIN_COORDS is an alias type for defining logical screen coordinates. It is defined as
typedef short WIN_COORDS;
SCR_RECT is a scructure (more precise, an union) for defining a rectangular area
using psysical screen coordinates. It is defined as
typedef union
{
struct
{
unsigned char x0, y0, x1, y1;
} xy;
unsigned long l;
} SCR_RECT;
Instead of giving four coordinates x0, y0, x1 and y1,
it is possible to give all together using a field l which is a packed long
number.
WIN_RECT is a scructure for defining a rectangular area using logical screen coordinates.
It is defined as
typedef struct
{
short x0, y0, x1, y1;
} WIN_RECT;
NOTE: TIGCC is a GNU C, so it allows cast constructors.
That's why, constructions like
WinOpen (&w, &(WIN_RECT){30, 30, 130, 80}, WF_SAVE_SCR);
are legal. See WinOpen for info about this command.
WINDOW is the main window-describing structure which is used in all window-based TIOS
functions. It is defied as
typedef struct WindowStruct
{
unsigned short Flags; // Window flags
unsigned char CurFont; // Current font
unsigned char CurAttr; // Current attribute
unsigned char Background; // Current background attribute
short TaskId; // Task ID of owner
short CurX, CurY; // Current (x,y) position (relative coordinates)
short CursorX, CursorY; // Cursor (x,y) position
SCR_RECT Client; // Client region of the window (excludes border)
SCR_RECT Window; // Entire window region including border
SCR_RECT Clip; // Current clipping region
SCR_RECT Port; // Port region for duplicate screen
unsigned short DupScr; // Handle of the duplicated or saved screen area
struct WindowStruct *Next; // Pointer to the next window in linked list
char *Title; // Pointer to the (optional) title
} WINDOW;
ICON is a structure which describes an icon (a 16x16 pixel area). It is defined as
typedef struct
{
unsigned short i[16];
} ICON;
NOTE: Texas Instruments said that exists a function named WinIcon. This is not true
as far as I know. At least, it is not in the jump table. But, function
DrawIcon surely exists...
pICON is a pointer to the ICON scructure. It is defined as
typedef unsigned short *pICON;
BITMAP_HDR_SIZE is a constant (with value 4) which defines the size of a header
of the BITMAP structure.
BITMAP is a structure for defining a bitmap, used in commands
like WinBitmapGet. It is defined as
typedef struct
{
unsigned short NumRows, NumCols;
unsigned char Data[0];
} BITMAP;
Note that Data[0] is GNU C extension for a variable-length areas (TIGCC is GNU C).