[Main]
Name=HomePushEStack
Type=Function
Subtype=ROM Call
Header Files=homescr.h
Definition=void HomePushEStack (void);
See Also=HomeStore, HomeStorePair, HS_popEStack

[ROM Call]
Index=$10F

[Description]
Creates and draws a new history pair with given contents.

[Explanation]
HomePushEStack is a very powerful command which lets you store expressions
straight to the history.
<BR><BR>
The expression (not a multi-expression) which you want to store to the
history has to be placed at the top of the expression stack. This function
will pop it off of the estack and into the history. It will be used as both
entry and answer, but it will not be simplified.
<BR><BR>
The result of using this call is that memory is allocated, so garbage
collection may occur. After your program exits, the allocated memory will
remain allocated, which is perfectly normal. However, kernels like
DoorsOS, TeOS, and PreOS (but not UniversalOS) have a feature that frees all
handles left unfreed by kernel programs. This feature is smart and first
checks if a handle is that of a variable, but older kernels do not check if
it is a history item.
<BR><BR>
For kernel-based programs, DoorsOS and TeOS will free the handles for the
newly stored item, and when your program exits, the calculator will crash!
PreOs 0.62 or higher detects the history handles and handles them correctly.
<BR><BR>
HomePushEStack calls
<A HREF="$$LINK(HS_newFIFONode)">HS_newFIFONode</A> and
<A HREF="$$LINK(HS_pushEmptyFIFONode)">HS_pushEmptyFIFONode</A> to create the
new history item.
<BR><BR>
<B>Note:</B> HomePushEStack redraws the home screen if it is the active
application, which it most likely is. To circumvent this, use
<A HREF="$$LINK(HomeStore)">HomeStore</A>.

[References]
Out=HS_countFIFO, HS_freeFIFONode, HS_newFIFONode, HS_pushEmptyFIFONode, HS_pushFIFONode, alloc.h/HeapAllocThrow, alloc.h/HeapFreeIndir, error.h/ER_catch, error.h/ER_success, error.h/ER_throwVar, estack.h/HToESI, estack.h/next_expression_index, estack.h/NG_RPNToText, estack.h/Parms2D, estack.h/Parse2DMultiExpr, estack.h/top_estack, graphing.h/gr_active, mem.h/memcpy, statline.h/ST_helpMsg, statline.h/ST_stack, string.h/strlen, system.h/XR_stringPtr, unknown.h/EV_currentApp, unknown.h/paint_all_except, wingraph.h/WinHeight, wingraph.h/WinWidth, unknown.h/_ROM_CALL_471, unknown.h/_ROM_CALL_5DD, unknown.h/_ROM_CALL_5DE
In=HomeStore, unknown.h/GT_IncXY, unknown.h/GT_Trace
