The <wingraph.h> Header File

Routines for windowed graphics

Functions

BitmapSizeExt

DrawStaticButton
Draws a button in a window.
DrawWinBorder
Draws a border of a window.
MakeWinRect
Builds a structure for representing rectangular area.
RectWinToScr
Converts relative to absolute coordinates then clips them to a window.
RectWinToScrExt
Converts relative to absolute coordinates then clips them to a window, taking into account negative coordinates.
RectWinToWin
Converts relative window coordinates to absolute coordinates.
SetWinClip
Changes the clipping area of a window.
WinActivate
Activates a window.
WinAttr
Sets the default window attribute.
WinBackground
Sets the default window background.
WinBackupToScr
Shows a current backup screen.
WinBegin
Setup a window for writing to without activating the window.
WinBeginPaint
Saves the current screen state of given window, and prepares the settings for drawing in the LCD memory.
WinBitmapGet
Gets a bitmap from a window.
WinBitmapPut
Puts a bitmap to a window.
WinBitmapSize
Determines a size of a bitmap (eventually clipped) in bytes.
WinBitmapSizeExt
Determines a size of a bitmap (eventually clipped) in bytes, taking into account negative coordinates.
WinChar
Draws a character to a window.
WinCharXY
Draws a series of characters to a window at the specific location.
WinClose
Closes a window.
WinClr
Clears a window.
WinDeactivate
Deactivates a window.
WinDupStat
Turns the duplicate status on or off.
WinEllipse
Draws an ellipse to a window.
WinEnd
Ends writing to a non-active window.
WinEndPaint
Restores the screen state saved with WinBeginPaint in given window.
WinFill
Draws a filled rectangle to a window.
WinFillLines2
Draws a filled area between two lines to a window.
WinFillTriangle
Draws a filled triangle to a window.
WinFont
Sets the current window font.
WinGetCursor
Returns the cursor location for a window.
WinHeight
Height of a window.
WinHide
Hides a window.
WinHome
Moves the pen location for a window to the home position.
WinLine
Draws a line to a window.
WinLineExt
Draws a line to a window, more accurately than WinLine when clipping.
WinLineNC
Draws a line to a window, without range checking.
WinLineRel
Draws a line to a window from the current pen position, using relative displacements.
WinLineTo
Draws a line to a window from the current pen position.
WinMoveCursor
Moves the pen position (???).
WinMoveRel
Sets the current window pen position relative to the previous position.
WinMoveTo
Sets the current window pen position.
WinOpen
Opens a new window.
WinPixGet
Gets the status of a pixel in a window.
WinPixSet
Sets a pixel in a window.
WinRect
Draws a rectangle to a window.
WinRemove
Closes the window pointed to by w, and frees the memory assigned to that window.
WinReOpen
Reopens an existing window.
WinScrollH
Shifts a region of a window left or right.
WinScrollV
Scrolls a region of a window upwards or downwards.
WinSetCursor
Moves the cursor (???).
WinShow
Makes a window visible for the repainting routine.
WinStr
Draws a string to a window.
WinStrXY
Draws a string to a window at a specific location.
WinStrXYWrap
Draws a word-wrapped string to a window at position x, y (window-based), and returns the height in pixels of the text drawn.
WinToScr
Converts a WIN_RECT into a SCR_RECT, clipping the coordinates if necessary.
WinWidth
Width of a window.

Global Variables

DeskTop
A pointer to the desktop window.
FirstWindow
A pointer to the head of the list of all windows.

Constants

BITMAP_HDR_SIZE
Defines the size of the header of the BITMAP structure.
NULL
A null-pointer value.

Predefined Types

Attrs
An enumeration for describing legal attribute values.
BITMAP
A structure for defining a bitmap.
Bool
An enumeration to describe true or false values.
BoxAttrs
An enumeration for describing addittional box attribute values.
Buttons
An enumeration to describe possible button types.
Fonts
An enumeration for describing legal font values.
HANDLE
Represents a handle associated with an allocated memory block.
ICON
A structure which describes an icon.
pICON
A pointer to the ICON scructure.
SCR_COORDS
An alias type for defining physical screen coordinates.
SCR_RECT
A scructure for defining a rectangular area.
SCR_STATE
A structure for saving the state of the graphics system.
WIN_COORDS
An alias type for defining logical screen coordinates.
WIN_RECT
A structure for defining a rectangular area.
WINDOW_AMS1
The main window-describing structure (AMS 1.xx version).
WINDOW
The main window-describing structure.
WinFlags
An enumeration for describing flags which control the window manager.
winWriteFlags
Enumeration for parameter flags to WinStrXYWrap.

See also: graph.h


BitmapSizeExt

AMS 2.00 or higher

unsigned short BitmapSizeExt (const WIN_RECT *WinRect);

See also: CalcBitmapSize


DrawStaticButton

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_OKButton "Enter=OK"
BT_SAVEButton "Enter=SAVE"
BT_YESButton "Enter=YES"
BT_CANCELButton "Esc=CANCEL"
BT_NOButton "ESC=NO"
BT_GOTOButton "Enter=GOTO"

Note: The current font (set using WinFont) must be F_4x6 for this function to work correctly.


DrawWinBorder

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.


MakeWinRect

WIN_RECT *MakeWinRect (short x0, short y0, short x1, short y1);

Builds a structure for representing rectangular area.

MakeWinRect accepts coordinates of two corners (x0y0) and (x1y1) 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 explicit 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.


RectWinToScr

SCR_RECT *RectWinToScr (const SCR_RECT *win_area, const WIN_RECT *rect, SCR_RECT *result_area);

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.


RectWinToScrExt

AMS 2.00 or higher

SCR_RECT *RectWinToScrExt (const SCR_RECT *win_area, const WIN_RECT *rect, SCR_RECT *result_area);

Converts relative to absolute coordinates then clips them to a window, taking into account negative coordinates.

See also: RectWinToScr


RectWinToWin

WIN_RECT *RectWinToWin (const SCR_RECT *win_area, WIN_RECT *rect);

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 structure pointed to by rect. RectWinToWin returns rect back (but note that the structure pointed to by it is modified).


SetWinClip

AMS 2.00 or higher

void SetWinClip (WINDOW *w, SCR_RECT *s);

Changes the clipping area of a window.

SetWinClip changes the clipping area of the window pointed to by w, to the SCR_RECT pointed to by s, and changes the contents of s from window-based to screen-based coordinates.

The original coordinates in s must be window-based, i.e (0,0) is the upper left corner of the window.


WinActivate

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:

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.


WinAttr

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_REVERSEDestination pixels turned off
A_NORMALDestination pixels turned on
A_XORSource pixels XORed with destination pixels
A_SHADEDDestination pixels masked so that every other pixel turned off
A_REPLACESource pixels replace destination pixels
A_ORSource pixels ORed with destination pixels

For lines the following additional attributes are supported:

A_THICK1Draw a double thick line
A_SHADE_VDraw the line using a vertical shading pattern
A_SHADE_HDraw the line using a horizontal shading pattern
A_SHADE_NSDraw the line using a negative slope diagonal shading pattern
A_SHADE_PSDraw 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!


WinBackground

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_NORMALBlack background
A_REVERSEWhite background
A_XORAll 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.


WinBackupToScr

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


WinBegin

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.


WinBeginPaint

AMS 2.00 or higher

void WinBeginPaint (WINDOW *w);

Saves the current screen state of given window, and prepares the settings for drawing in the LCD memory.

WinBeginPaint just saves the current screen state in w->savedScrState, executes PortRestore and sets the current font to w->CurFont. So, emulating it on AMS 1.xx is easy.
WinBeginPaint is always paired with WinEndPaint which restores the screen state.
WinBeginPaint is commonly used to respond a CM_ACTIVATE message.

See also: WinEndPaint


WinBitmapGet

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.


WinBitmapPut

void 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 WinBitmapGet) to the window pointed to by w at the position (xy), 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_REPLACEReplace the destination region with the source bitmap
A_REVERSEReplace the destination region with the inverse of the source bitmap
A_XORExculsive-OR the source bitmap into the destination region
A_OROR the source bitmap into the destination region
A_ANDAND the source bitmap into the destination region
A_SHADEDMask 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.


WinBitmapSize

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.

See also: WinBitmapSizeExt


WinBitmapSizeExt

AMS 2.00 or higher

unsigned short WinBitmapSizeExt (WINDOW *w, const WIN_RECT *WinRect);

Determines a size of a bitmap (eventually clipped) in bytes, taking into account negative coordinates.

The difference between WinBitmapSize and WinBitmapSizeExt is that WinBitmapSizeExt takes into account negative coordinates. So, use WinBitmapSize if negative coordinates have to be clipped to zero.

See also: CalcBitmapSize, WinBitmapGet, WinBitmapPut, WinBitmapSize


WinChar

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_NORMALThe character is ORed into the destination
A_REVERSEThe region created by inversing the character replaces the destination
A_REPLACEThe region defined by the character replaces the destination
A_XORThe character is XORed into the destination
A_SHADEDThe 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.

Note: On all AMS versions, WinChar calls most of the time a subroutine which is exported in the jump table on AMS 2.xx as ROM_CALL_412. It doesn't call it if the window is opened in TTY mode and the character is '\n', '\r' or '\f'. As a consequence, that subroutine is not of much use, as the same effect (showing these characters as symbols) can be obtained by unsetting the WF_TTY flag. It is mentioned here only for completeness.


WinCharXY

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 (xy) 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.


WinClose

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.


WinClr

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.


WinDeactivate

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.


WinDupStat

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.


WinEllipse

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 (xy) 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_NORMALDraw a elipse
A_REVERSEErase a ellipse
A_XORXORs a ellipse into the destination

Note: Set a=b to draw a circle.


WinEnd

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.


WinEndPaint

AMS 2.00 or higher

void WinEndPaint (WINDOW *w);

Restores the screen state saved with WinBeginPaint in given window.

WinEndPaint(&w); does nothing more than RestoreScrState(&(w.savedScrState));
WinEndPaint is always paired with WinBeginPaint, and it is commonly used to respond a CM_DEACTIVATE message.

See also: WinBeginPaint


WinFill

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_NORMALFill with black pixels
A_REVERSEFill with white pixels
A_XORAll 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.


WinFillLines2

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".


WinFillTriangle

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 (x0y0), (x1y1) and (x2y2) 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_NORMALDraws a solid fill triangle
A_REVERSEDraws an empty triangle (i.e. erase a triangular area)
A_XORXORs a solid fill triangle into the destination
A_SHADE_VDraws a triangle filled using a vertical shading pattern
A_SHADE_HDraws a triangle filled using a horizontal shading pattern
A_SHADE_NSDraws a triangle filled using a negative slope diagonal shading pattern
A_SHADE_PSDraws 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).


WinFont

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.


WinGetCursor

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.


WinHeight

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.


WinHide

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).


WinHome

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.


WinLine

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.


WinLineExt

AMS 2.00 or higher

void WinLineExt (WINDOW *w, const WIN_RECT *Line);

Draws a line to a window, more accurately than WinLine when clipping.

WinLineExt acts like WinLine, except that clipping is done more smoothly and drawing is sometimes more accurate: instead of just clipping the coordinates to the window clipping area, as WinLine does, WinLineExt draws the line between the endpoints, drawing only the pixels that are in the window clipping area.
This can lead to little differences between a line drawn by WinLine and the same line drawn by WinLineExt.

The drawback is that WinLineExt is slower than WinLine.

See also: WinAttr, WinLine, WinLineRel, WinLineTo


WinLineNC

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.


WinLineRel

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.


WinLineTo

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 (xy) 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_NORMALDraw a normal line
A_REVERSEDraw an inverse line (i.e. erase the line)
A_XORDraw a line using XORing with the destination
A_THICK1Draw a double thick line
A_SHADE_VDraw the line using a vertical shading pattern
A_SHADE_HDraw the line using a horizontal shading pattern
A_SHADE_NSDraw the line using a negative slope diagonal shading pattern
A_SHADE_PSDraw 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!


WinMoveCursor

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!!!


WinMoveRel

void WinMoveRel (WINDOW *w, short dx, short dy);

Sets the current window pen position relative to the previous position.

WinMoveRel acts like WinMoveTo, but dx and dy are relative to the current pen position.


WinMoveTo

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 (xy). 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.


WinOpen

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, and 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 defined in Flags may be set as one or more of the following constants defined in the enum WinFlags (they have to be ORed; note that 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 make the window's border bold.
WF_NOBORDER Do not draw a border around the window.
WF_ROUNDEDBORDER Draw a rounded border instead of rectangular border (this option implies WF_NOBOLD as well).
WF_TITLE Draw a title bar; in this case the Flags parameter must be followed by a text string which will be used as the window title (according to my experience, it seems that only windows with rounded borders may have title bars).
WF_VIRTUAL Set this flag for virtual windows which are just allocated bitmaps in memory and which are not limited to the size of the screen; no writes to actual LCD are done, 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 the save buffer, else returns TRUE. Here is an example (called "Window 4") which displays "hello everyone" in a window (assuming that there were no errors):

#define USE_TI89              // Compile for TI-89
#define USE_TI92PLUS          // Compile for TI-92 Plus
#define USE_V200              // Compile for V200

#define OPTIMIZE_ROM_CALLS    // Use ROM Call Optimization
#define MIN_AMS 100           // Compile for AMS 1.00 or higher
#define SAVE_SCREEN           // Save/Restore LCD Contents

#include <tigcclib.h>         // Include All Header Files

// Main Function
void _main(void)
{
  WINDOW *wind = HeapAllocPtr (sizeof (WINDOW));
  WinOpen (wind, MakeWinRect (20, 20, 80, 50), WF_SAVE_SCR | WF_TTY);
  WinActivate (wind);
  WinFont (wind, F_6x8);
  WinStr (wind, "hello everyone");
  ngetchx ();
  WinClose (wind);
  HeapFreePtr (wind);
}

Like any other function which allocates a memory block, WinOpen may cause heap compression.

Note: You must call WinActivate to display a window on the screen, although TI said that you do not need to do so. Also, don't forget to close all windows (using WinClose or WinRemove) before the end of the program, else the TI will crash later, when the TIOS window manager tries to refresh a window in the list which ceased to exist after terminating the program!


WinPixGet

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 (xy), 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.


WinPixSet

void WinPixSet (WINDOW *w, short x, short y);

Sets a pixel in a window.

WinPixSet set a pixel at (xy) 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_NORMALDraw a pixel
A_REVERSEErase a pixel
A_XORInvert a pixel


WinRect

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_NORMALDraw a normal rectangle
B_DOUBLEDraw a double thick rectangle
B_ROUNDEDDraw a rectangle with rounded corners
B_CUTDraw 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.


WinRemove

void WinRemove (WINDOW *w, short UpdateScreen);

Closes the window pointed to by w, and frees the memory assigned to that window.

If UpdateScreen is TRUE, the next window in the linked list of windows is activated and the screen is updated.
If UpdateScreen is FALSE, no window is activated and the screen is not updated.
In fact, WinClose calls WinRemove with UpdateScreen = TRUE on all AMS versions.
Virtual windows (the ones with WF_VIRTUAL flag set) should be closed with:

WinRemove(&w,FALSE);

See also: WinClose, WinOpen


WinReOpen

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.


WinScrollH

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.


WinScrollV

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.


WinSetCursor

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.


WinShow

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).


WinStr

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.


WinStrXY

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 (xy) location (the coordinates are relative to the topleft corner of the window). See WinStr for more info.


WinStrXYWrap

AMS 2.04 or higher

short WinStrXYWrap (WINDOW *w, WIN_COORDS x, WIN_COORDS y, const char *s, unsigned short flags);

Draws a word-wrapped string to a window at position x, y (window-based), and returns the height in pixels of the text drawn.

w is the pointer to a window.
x and y is the place where to draw the string, x is also the left margin to wrap on.
s is the pointer to the string to write.
flags: correct values are described in winWriteFlags.

This function is available in the jump table only on AMS 2.04 and later, and the parameter WWF_WRAP_BACK_TO_ZERO is taken into account only on AMS 2.07 and later.

See also: winWriteFlags


WinToScr

AMS 2.00 or higher

SCR_RECT *WinToScr (const WIN_RECT *win_rect, SCR_RECT *dest_rect);

Converts a WIN_RECT into a SCR_RECT, clipping the coordinates if necessary.

WinToScr converts coordinates (shorts) in the structure win_rect to the same coordinates (unsigned char), storing the result in the structure pointed to by dest_rect, except that the coordinates that are negative are clipped to 0, and the coordinates greater than 0xFF are clipped to 0xFF. WinToScr returns dest_rect back (but the structure pointed to by it is modified).

If you want a WinToScr that works on all AMS versions, you can use:

#undef WinToScr
SCR_RECT *WinToScr (const WIN_RECT *win_rect, SCR_RECT *dest_rect);
asm("
WinToScr:
move.l   4(%sp),%a1
move.l   8(%sp),%a0
moveq    #4-1,%d1
_loop_WTS_:
move.w   (%a1)+,%d0
bge.s    _not_negative_WTS_
moveq    #0,%d0 | clr.w %d0 or eor.w %d0,%d0 are enough and just as fast.
bra.s    _store_WTS_
_not_negative_WTS_:
cmpi.w   #0xFF,%d0
bls.s    _store_WTS_
moveq    #-1,%d0
_store_WTS_:
move.b   %d0,(%a0)+
dbf      %d1,_loop_WTS_
subq.l   #4,%a0
rts
");

WinWidth

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.


DeskTop

WINDOW *const DeskTop;

A pointer to the desktop window.

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).


FirstWindow

WINDOW *FirstWindow;

A pointer to the head of the list of all windows.

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.


WIN_COORDS

typedef short WIN_COORDS;

An alias type for defining logical screen coordinates.


WIN_RECT

typedef struct {
short x0, y0, x1, y1;
} WIN_RECT;

A structure for defining a rectangular area.

WIN_RECT is a scructure for defining a rectangular area using logical screen coordinates.

Note: TIGCC is derived from 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_AMS1

typedef struct WindowStruct_AMS1 {
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 the linked list */
char *Title; /* Pointer to the (optional) title */
} WINDOW_AMS1;

The main window-describing structure (AMS 1.xx version).

WINDOW_AMS1 is the AMS 1.xx version of the WINDOW structure. It is a little smaller, since the last two fields are missing. Usually, this is not important, but it is a problem if a window structure is included in other structures (like EQU_DS).

See also: WINDOW


WINDOW

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 the linked list */
char *Title; /* Pointer to the (optional) title */
SCR_STATE savedScrState; /* Saved state of the graphics system */
unsigned char Reserved[16]; /* Reserved, do not use */
} WINDOW;

The main window-describing structure.

WINDOW is the main window-describing structure which is used in all window-based TIOS functions.


WinFlags

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};

An enumeration for describing flags which control the window manager.

These flags are used in the 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).

WF_DIRTY and WF_VISIBLE are used in event driven applications, see EV_paintOneWindow function.


winWriteFlags

AMS 2.04 or higher

enum winWriteFlags {
WWF_DRAW = 1, WWF_WRAP_ON_COMMAS = 2, WWF_WRAP_BACK_TO_ZERO = 4
};

Enumeration for parameter flags to WinStrXYWrap.

WWF_DRAW means that the function will draw the string. If it is not set in the flags, the height of the text drawn is returned and nothing else is done.
WWF_WRAP_ON_COMMAS means that the function will also wrap on commas, not only on spaces (\x20) and carriage returns (\x0A).
WWF_WRAP_BACK_TO_ZERO means that the function will go back to the first column of the window after the first line. This option is available only on AMS 2.07 and more.

See also: WinStrXYWrap


Return to the main index