the handle to my system-level banner window

The creator-assigned ID string to identify the banner persistently. This is only needed for banners created dynamically; for BannerWindow objects defined statically at compile time, simply leave this value as nil, and we'll use the object itself as the identifier.

flag: this banner has been initialized with initBannerWindow()

Creation parameters. We store these when we create the banner, and update them as needed when the banner's display attributes are changed.

Clear my banner window. This clears out all of the contents of our on-screen display area.

Construct the object.

'id' is a globally unique identifying string for the banner. When we dynamically create a banner object, we have to provide a unique identifying string, so that we can correlate transient on-screen banners with the banners in a saved state when restoring the saved state.

Note that no ID string is needed for BannerWindow objects defined statically at compile-time, because the object itself ('self') is a suitably unique and stable identifier.

create our banner output stream

Create the system-level banner window. This can be customized as needed, although this default implementation should be suitable for most instances.

Returns true if we are successful in creating the system window, nil if we fail.

Move the cursor to the given row/column position. This can only be used with text-grid banners; for ordinary text banners, this has no effect.

flush any pending output to the banner

Get the banner identifier. If our 'id_' property is set to nil, we'll assume that we're a statically-defined object, in which case 'self' is a suitable identifier. Otherwise, we'll return the identifier string.

Initialize the banner window. This is called during initialization (when first starting the game, or when resetting with RESTART). If the banner is to be displayed from the start of the game, this can set up the on-screen display.

Note that we might already have an on-screen handle when this is called. This indicates that we're restarting an ongoing session, and that this banner already existed in the session before the RESTART operation. If desired, we can attach ourselves to the existing on-screen banner, avoiding the redrawing that would occur if we created a new window.

If this window depends upon another window for its layout order placement (i.e., we'll call showBanner() with another BannerWindow given as the 'other' parameter), then this routine should call the other window's initBannerWindow() method before creating its own window, to ensure that the other window has a system window and thus will be meaningful to establish the layout order.

Overriding implementations should check the 'inited_' property. If this property is true, then it can be assumed that we've already been initialized and don't require further initialization. This routine can be called multiple times because dependent windows might call us directly, before we're called for our regular initialization.

Remove the banner. This removes the banner's on-screen window. The BannerWindow object itself remains valid, but after this method returns, the BannerWindow no longer has an associated display window.

Note that any child banners of ours will become undisplayable after we're gone. A child banner depends upon its parent to obtain display space, so once the parent is gone, its children no longer have any way to obtain any display space. Our children remain valid objects even after we're closed, but they won't be visible on the display.

set the screen color in the banner window

Set the banner window to a specific size. 'size' is the new size, in units given by 'sizeUnits', which is a BannerSizeXxx constant.

'isAdvisory' is true or nil; if true, it indicates that the size setting is purely advisory, and that a sizeToContents() call will eventually follow to set the actual size. When 'isAdvisory is true, the interpreter is free to ignore the request if sizeToContents()

set the text color in the banner

Show the banner. The game should call this method when it first wants to display the banner.

'parent' is the parent banner; this is an existing BannerWindow object. If 'parent' is nil, then the parent is the main game text window. The new window's display space is obtained by carving space out of the parent's area, according to the alignment and size values specified.

'where' and 'other' give the position of the banner among the children of the given parent. 'where' is one of the constants BannerFirst, BannerLast, BannerBefore, or BannerAfter. If 'where' is BannerBefore or BannerAfter, 'other' gives the BannerWindow object to be used as the reference point in the parent's child list; 'other' is ignored in other cases. Note that 'other' must always be another child of the same parent; if it's not, then we act as though 'where' were given as BannerLast.

'windowType' is a BannerTypeXxx constant giving the new window's type.

'align' is a BannerAlignXxx constant giving the alignment of the new window. 'size' is an integer giving the size of the banner, in units specified by 'sizeUnits', which is a BannerSizeXxx constant. If 'size' is nil, it indicates that the caller doesn't care about the size, usually because the caller will be resizing the banner soon anyway; the banner will initially have zero size in this case if we create a new window, or will retain the existing size if there's already a system window.

'styleFlags' is a combination of BannerStyleXxx constants (combined with the bitwise OR operator, '|'), giving the requested display style of the new banner window.

Note that if we already have a system banner window, and the existing banner window has the same characteristics as the new creation parameters, we'll simply re-use the existing window rather than closing and re-creating it; this reduces unnecessary redrawing in cases where the window isn't changing. If the caller explicitly wants to create a new window even if we already have a window, the caller should simply call removeBanner() before calling this routine.

Restore this banner. This is called after a RESTORE or UNDO operation that finds that this banner was being displayed at the time the state was saved but is not currently displayed in the active UI. We'll show the banner using the characteristics saved persistently.

Size the banner to its current contents. Note that some systems do not support this operation, so callers should always make an advisory call to setSize() first to set a size based on the expected content size.

Update my contents after being restored. By default, this does nothing; instances might want to override this to refresh the contents of the banner if the banner is normally updated only in response to specific events. Note that it's not necessary to do anything here if the banner will soon be updated automatically as part of normal processing; for example, the status line banner is updated at each new command line via a prompt-daemon, so there's no need for the status line banner to do anything here.

write the given text to the banner