</R>Purpose<!R>
A scrolling window widget allows the programmer to display a scrolling message
window. This widget allows a programmer to add current messages to the window. 
This type of widget is best used for a log file.

</R>Construction Options<!R>
A swindow widget is defined using the following syntax. The variable
$swindowObject<!B> contains a reference to the swindow object.
<C>$swindowObject = new Cdk::Swindow ( options );
 
The options are defined in the following table.

Option      Default Value       Type       Purpose<!U>
Title       Required            Scalar     The title of the scrolling window.
Lines       Required            Scalar     The number of lines to keep.
Height      Required            Scalar     The height of the scrolling window.
Width       Required            Scalar     The width of the scrolling window.
Xpos        Center              Scalar     This is the position of the window on the X axis.
Ypos        Center              Scalar     This is the position of the window on the Y axis.
Box         True                Scalar     This boolean states whether the dialog box will have a box drawn around it.
Shadow      False               Scalar     This boolean states whether the dialog box will have a shadow on the box.

</R>Available Methods<!R>
activate<!B>
Activation of an object means to make the object available for use. The 
following example demonstrates how to activate a swindow widget.
<C>$swindowObject->activate ();

inject<!B>
This function injects a single character into the widget. The following
examples demonstrates how to call the inject method.
<C>$swindowObject->inject ( options );

The options are defined in the following table.
Option      Default Value       Type       Purpose<!U>
Shadow      Required             Scalar     The character to inject into the widget.

If you are injecting a special character into the widget, then you can
use a pre-defined value to represent the key.

<C><#UL><#HL(12)><#TT><#HL(15)><#UR>
<C><#VL>Key         <#VL>Key Value      <!U><#VL>
<C><#VL>Left Arrow  <#VL>KEY_LEFT       <#VL>
<C><#VL>Right Arrow <#VL>KEY_RIGHT      <#VL>
<C><#VL>Up Arrow    <#VL>KEY_UP         <#VL>
<C><#VL>Down Arrow  <#VL>KEY_DOWN       <#VL>
<C><#VL>Delete      <#VL>KEY_DELETE     <#VL>
<C><#VL>Backspace   <#VL>KEY_BACKSPACE  <#VL>
<C><#VL>Page Up     <#VL>KEY_PPAGE      <#VL>
<C><#VL>Page Down   <#VL>KEY_NPAGE      <#VL>
<C><#VL>Home        <#VL>KEY_HOME       <#VL>
<C><#VL>End         <#VL>KEY_END        <#VL>
<C><#VL>Escape      <#VL>KEY_ESC        <#VL>
<C><#LL><#HL(12)><#BT><#HL(15)><#LR>

set<!B>
Sets or resets certain attributes or features of the widget. The following
example demonstrates how to call the set method.
<C>$swindowObject->set ( options );

The options are defined in the following table.

Option      Default Value       Type       Purpose<!U>
Info        Required            Array Ref  Sets the contents of the window.
Lines       Required            Scalar     Sets the number of lines to keep.
Box         True                Scalar     Changes the current value of the box flag.

bind<!B>
The bind method binds keys to events. The binding is specific to the individual
objects. The following example demonstrates how to call the bind method.
<C>$swindowObject->bind ( options );

The options are defined in the following table.

Option      Default Value       Type       Purpose<!U>
Key         Required            Scalar     This is the character to bind the event to.
Function    Required            Scalar     This is the name of the callback function.

preProcess<!B>
The preProcess<!B> function sets a process to be run before the key entered
is processed. If this function returns a value of 0, then the key injected
into the widget will not be processed; otherwise the character will be
processed as normal.  The following example demonstrates how to call the
preProcess method.
<C>$swindowObject->preProcess ( options );

The options are defined in the following table.

Option      Default Value       Type       Purpose<!U>
Function    Required            Scalar     This is the name of the
                                           callback function.

To create a pre-process callback the following code segment demonstrates
how to do it properly.

<C>$swindowObject->preProcess ('Function' => sub { callback (@_); });

Notice that the array @_<!B> is passed into the function called
callback<!B>. This is done because when the callback process is 
called the key which was pressed is passed into the perl subroutine.
Since we nest the call-back function inside an anonymous subroutine,
we need to pass the array @_<!B> to the call-back function. If
the key given to the call-back function is a non alphanumeric key
then a predefined value will be given to the function. The following
table describes the values passed into the function.

<C><#UL><#HL(12)><#TT><#HL(15)><#UR>
<C><#VL>Key         <#VL>Key Value      <!U><#VL>
<C><#VL>Left Arrow  <#VL>KEY_LEFT       <#VL>
<C><#VL>Right Arrow <#VL>KEY_RIGHT      <#VL>
<C><#VL>Up Arrow    <#VL>KEY_UP         <#VL>
<C><#VL>Down Arrow  <#VL>KEY_DOWN       <#VL>
<C><#VL>Delete      <#VL>KEY_DELETE     <#VL>
<C><#VL>Backspace   <#VL>KEY_BACKSPACE  <#VL>
<C><#VL>Page Up     <#VL>KEY_PPAGE      <#VL>
<C><#VL>Page Down   <#VL>KEY_NPAGE      <#VL>
<C><#VL>Home        <#VL>KEY_HOME       <#VL>
<C><#VL>End         <#VL>KEY_END        <#VL>
<C><#VL>Escape      <#VL>KEY_ESC        <#VL>
<C><#LL><#HL(12)><#BT><#HL(15)><#LR>

If the pre-process function returns a value of 0 the key hit will
not be injected into the widget. This allows the programmer to
selectively pick which characters will or will not get injected
into the widget.

The postProcess<!B> function sets a process to be run before the key entered
is processed. If this function returns a value of 0, then the key injected
into the widget will not be processed; otherwise the character will be
processed as normal.  The following example demonstrates how to call the
postProcess method.
<C>$swindowObject->postProcess ( options );

The options are defined in the following table.

Option      Default Value       Type       Purpose<!U>
Function    Required            Scalar     This is the name of the
                                           callback function.

To create a post-process callback the following code segment demonstrates
how to do it properly.

<C>$swindowObject->postProcess ('Function' => sub { callback (@_); });

Notice that the array @_<!B> is passed into the function called
callback<!B>. This is done because when the callback process is 
called the key which was pressed is passed into the perl subroutine.
Since we nest the call-back function inside an anonymous subroutine,
we need to pass the array @_<!B> to the call-back function. If
the key given to the call-back function is a non alphanumeric key
then a predefined value will be given to the function. The following
table describes the values passed into the function.

<C><#UL><#HL(12)><#TT><#HL(15)><#UR>
<C><#VL>Key         <#VL>Key Value      <!U><#VL>
<C><#VL>Left Arrow  <#VL>KEY_LEFT       <#VL>
<C><#VL>Right Arrow <#VL>KEY_RIGHT      <#VL>
<C><#VL>Up Arrow    <#VL>KEY_UP         <#VL>
<C><#VL>Down Arrow  <#VL>KEY_DOWN       <#VL>
<C><#VL>Delete      <#VL>KEY_DELETE     <#VL>
<C><#VL>Backspace   <#VL>KEY_BACKSPACE  <#VL>
<C><#VL>Page Up     <#VL>KEY_PPAGE      <#VL>
<C><#VL>Page Down   <#VL>KEY_NPAGE      <#VL>
<C><#VL>Home        <#VL>KEY_HOME       <#VL>
<C><#VL>End         <#VL>KEY_END        <#VL>
<C><#VL>Escape      <#VL>KEY_ESC        <#VL>
<C><#LL><#HL(12)><#BT><#HL(15)><#LR>
draw<!B>
This method draws the object on the screen. The following example demonstrates
how to call the draw method.
<C>$swindowObject->draw ( options );

The options are defined in the following table.

Option      Default Value       Type       Purpose<!U>
Box         True                Scalar     Draws the window with a box around it.

addline<!B>
This method adds a line to the scrolling window. The following example
demonstrates how to call the addline method.
<C>$swindowObject->addline ( options );

The options are defined in the following table.

Option      Default Value       Type       Purpose<!U>
Info        Required            Scalar     The information to add to the window.
Position    Bottom              Scalar     The location where the information is to be added.

trim<!B>
This method trims the information maintained by the srolling window. The following
example demonstrates how to call the trim method.
<C>$swindowObject->trim ( options );

The options are defined in the following table.

Option      Default Value       Type       Purpose<!U>
Start       Required            Scalar     This is the first line to trim from.
Finish      Required            Scalar     This is the last line to trim from.

get<!B>
This method returns the information currently in the srolling window. The
following example demonstrates how to call the get method.
<C>@information = $swindowObject->get ();

erase<!B>
This method removes the object from the screen. This does </B/U>NOT<!B!U> 
destroy the object. The following example demonstrates how to call the erase 
method.
<C>$swindowObject->erase ();

raise<!B>
The raise method raises the widget to the top of the screen. This means if there
were any widgets obscuring part of the view, raising the object would bring the
complete object into view. The following example demonstrates how to call the 
raise method.
<C>$swindowObject->raise();

lower<!B>
The lower method lowers the object so it doesn't obscure the view of any other 
objects. The following example demonstrates how to call the lower method.
<C>$swindowObject->lower();

register<!B>
The register method registers the object to the default screen. This does </R>NOT<!R>
have to be called since the objects are registered automatically. This method
should be called if the unregister<!B> method was called. The following
example demonstrates how to call the register method.
<C>$swindowObject->register();

unregister<!B>
The unregister method should be called when a widget, which is part of the
default screen, needs to be taken away temporarily. This does not delete or free
the object, it just unmaps it from any future screen refreshes. The object can
be registered by calling the register<!B> method. The following example
demonstrates how to call the unregister method.
<C>$swindowObject->unregister();

getwin<!B>
This method returns a pointer to the window of the object. Not much use for this
yet. It will be useful in the future when the drawing methods are added. The
following example demonstrates how to call the getwin method.
<C>$swindowObject->getwin();

</R>Default Key Bindings<!R>
Key               Action<!U>
Up Arrow          Scrolls the window up by one line.
Down Arrow        Scrolls the window down by one line.
Right Arrow       Scrolls the window right by one line.
Left Arrow        Scrolls the window left by one line.
Prev Page         Displays the previous page.
CTRL-B            Displays the previous page.
B                 Displays the previous page.
b                 Displays the previous page.
Next Page         Displays the next page.
CTRL-F            Displays the next page.
Space             Displays the next page.
F                 Displays the next page.
f                 Displays the next page.
Home              Moves to the far left of the window.
|                 Moves to the far left of the window.
End               Moves to the far right of the window.
$                 Moves to the far right of the window.
g                 Moves to the top of the window.
1                 Moves to the top of the window.
G                 Moves to the bottom of the window.
L                 Moves halfway to the bottom of the scrolling window.
l                 Moves halfway to the top of the scrolling window.
Return            Exits the scrolling window.
Tab               Exits the scrolling window.
CTRL-R            Refreshes the screen.

</R>Tips & Tricks<!R>
None.

</R>Physical Restrictions<!R>
Restriction                    Value<!U>
Maximum number of lines.        300

</R>Example Use Of The Widget<!R>
<F=../examples/swindow>
<C><#HL(70)>
<C>Document Created: June,     1995
<C>Document Revised: November, 1995
<C>Document Revised: June,     1995
<C>Document Revised: March,    2012
