[Main]
Name=WinOpen
Type=Function
Subtype=ROM Call
Header Files=wingraph.h
Definition=short WinOpen (WINDOW *w, const WIN_RECT *rect, unsigned short Flags, ...);

[ROM Call]
Index=$1E

[Description]
Opens a new window.

[Explanation]
WinOpen opens a new window, initializing all fields of the
<A HREF="$$LINK(wingraph.h/WINDOW)">WINDOW</A> structure pointed to by <I>w</I>, and then links this window into the
current list of windows as the topmost window. <I>rect</I> is the pointer
to the rectangular structure of type <A HREF="$$LINK(wingraph.h/WIN_RECT)">WIN_RECT</A> which defines the
window area. The flags defined in <I>Flags</I> may be
set as one or more of the following constants defined in the enum <A HREF="$$LINK(wingraph.h/WinFlags)">WinFlags</A>
(they have to be ORed; note that WF_SAVE_SCR and WF_DUP_SCR are mutually exclusive):
<BR><BR>
<TABLE BORDER CELLPADDING="3">
<TR><TD VALIGN="TOP">WF_SAVE_SCR</TD>
<TD>Save the screen region underneath the window (restore it when the window is closed).</TD>
</TR>
<TR><TD VALIGN="TOP">WF_DUP_SCR</TD>
<TD>Keep a duplicate copy of all data written to the window; when the window needs to be
updated, the application will not receive a <A HREF="$$LINK(events.h/EventIDs)">CM_WPAINT</A> message, instead the system will update
the window (see <A HREF="$$LINK(events.h/EV_paintOneWindow)">EV_paintOneWindow</A> for more info).</TD>
</TR>
<TR><TD VALIGN="TOP">WF_TTY</TD>
<TD VALIGN="TOP">Write characters in TTY mode (translate '\n' and '\r' to a newline, '\f' to clear screen, and wrap
at end of lines).</TD>
</TR>
<TR><TD VALIGN="TOP">WF_NOBOLD</TD>
<TD VALIGN="TOP">When window is activated, do not make the window's border bold.</TD>
</TR>
<TR><TD VALIGN="TOP">WF_NOBORDER</TD>
<TD VALIGN="TOP">Do not draw a border around the window.</TD>
</TR>
<TR><TD VALIGN="TOP">WF_ROUNDEDBORDER</TD>
<TD VALIGN="TOP">Draw a rounded border instead of rectangular border (this option implies WF_NOBOLD as well).</TD>
</TR>
<TR><TD VALIGN="TOP">WF_TITLE</TD>
<TD VALIGN="TOP">Draw a title bar; in this case the <I>Flags</I> 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).</TD>
</TR>
<TR><TD VALIGN="TOP">WF_VIRTUAL</TD>
<TD VALIGN="TOP">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).</TD>
</TR>
</TABLE>
<BR>
WinOpen returns <A HREF="$$LINK(alloc.h/Bool)">FALSE</A> if there is not enough memory to
allocate the save buffer, else returns <A HREF="$$LINK(alloc.h/Bool)">TRUE</A>. Here is an example
(called "Window 4") which displays "hello everyone" in a window (assuming that there were no errors):
$$EXAMPLE(Window 4.c)
Like any other function which allocates a memory block, WinOpen may cause
heap compression.
<BR><BR>
<B>Note:</B> You must call <A HREF="$$LINK(wingraph.h/WinActivate)">WinActivate</A> to display a window on the screen,
although TI said that you do not need to do so. Also, don't forget to <B>close</B> all windows
(using <A HREF="$$LINK(wingraph.h/WinClose)">WinClose</A> or <A HREF="$$LINK(wingraph.h/WinRemove)">WinRemove</A>)
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!

[References]
In=wingraph.h/WinReOpen, assert.h/assert, bascmd.h/cmd_newpic, bascmd.h/cmd_showstat, dialogs.h/Dialog, error.h/ERD_dialog, events.h/ABT_dialog, events.h/EV_defaultHandler, events.h/handleVarLinkKey, system.h/HelpKeys, error.h/ERD_notice, unknown.h/EV_quit, unknown.h/_ROM_CALL_45B
Out=wingraph.h/FirstWindow, wingraph.h/WinClr, wingraph.h/WinHome, alloc.h/HeapAlloc, graph.h/BitmapGet, graph.h/BitmapInit, graph.h/BitmapSize, mem.h/memcpy, mem.h/memset, unknown.h/EV_runningApp
