554 lines
14 KiB
Groff
554 lines
14 KiB
Groff
'\" t
|
|
.\" $Id: cdk_swindow.3,v 1.25 2016/12/11 01:21:42 tom Exp $
|
|
.de bP
|
|
.IP \(bu 4
|
|
..
|
|
.de XX
|
|
..
|
|
.TH cdk_swindow 3
|
|
.SH NAME
|
|
.XX activateCDKSwindow
|
|
.XX addCDKSwindow
|
|
.XX cleanCDKSwindow
|
|
.XX destroyCDKSwindow
|
|
.XX drawCDKSwindow
|
|
.XX dumpCDKSwindow
|
|
.XX eraseCDKSwindow
|
|
.XX execCDKSwindow
|
|
.XX getCDKSwindowBox
|
|
.XX getCDKSwindowContents
|
|
.XX injectCDKSwindow
|
|
.XX jumpToLineCDKSwindow
|
|
.XX loadCDKSwindowInformation
|
|
.XX moveCDKSwindow
|
|
.XX newCDKSwindow
|
|
.XX positionCDKSwindow
|
|
.XX saveCDKSwindowInformation
|
|
.XX setCDKSwindow
|
|
.XX setCDKSwindowBackgroundAttrib
|
|
.XX setCDKSwindowBackgroundColor
|
|
.XX setCDKSwindowBox
|
|
.XX setCDKSwindowBoxAttribute
|
|
.XX setCDKSwindowContents
|
|
.XX setCDKSwindowHorizontalChar
|
|
.XX setCDKSwindowLLChar
|
|
.XX setCDKSwindowLRChar
|
|
.XX setCDKSwindowPostProcess
|
|
.XX setCDKSwindowPreProcess
|
|
.XX setCDKSwindowULChar
|
|
.XX setCDKSwindowURChar
|
|
.XX setCDKSwindowVerticalChar
|
|
.XX trimCDKSwindow
|
|
cdk_swindow \- a curses scrolling window widget.
|
|
.SH SYNOPSIS
|
|
.LP
|
|
.B cc
|
|
.RI "[ " "flag" " \|.\|.\|. ] " "file" " \|.\|.\|."
|
|
.B \-lcdk
|
|
.RI "[ " "library" " \|.\|.\|. ]"
|
|
.LP
|
|
#include <cdk.h>
|
|
.nf
|
|
.TP 15
|
|
.B "void activateCDKSwindow ("
|
|
.BI "CDKSWINDOW *" "swindow",
|
|
.BI "chtype * " "actions");
|
|
.TP 15
|
|
.B "void addCDKSwindow ("
|
|
.BI "CDKSWINDOW *" "swindow",
|
|
.BI "const char *" "info",
|
|
.BI "int " "insertPosition");
|
|
.TP 15
|
|
.B "void cleanCDKSwindow ("
|
|
.BI "CDKSWINDOW *" "swindow");
|
|
.TP 15
|
|
.B "int execCDKSwindow ("
|
|
.BI "CDKSWINDOW *" "swindow",
|
|
.BI "const char * " "command",
|
|
.BI "int " "insertPosition");
|
|
.TP 15
|
|
.B "void destroyCDKSwindow ("
|
|
.BI "CDKSWINDOW *" "swindow");
|
|
.TP 15
|
|
.B "void drawCDKSwindow ("
|
|
.BI "CDKSWINDOW *" "swindow",
|
|
.BI "boolean " "box");
|
|
.TP 15
|
|
.B "void dumpCDKSwindow ("
|
|
.BI "CDKSWINDOW *" "swindow",
|
|
.BI "const char *" "filename");
|
|
.TP 15
|
|
.B "void eraseCDKSwindow ("
|
|
.BI "CDKSWINDOW *" "swindow");
|
|
.B "void execCDKSwindow ("
|
|
.BI "CDKSWINDOW *" "swindow,"
|
|
.BI "char *" "command,"
|
|
.BI "int " "insertPosition);"
|
|
.B "boolean getCDKSwindowBox ("
|
|
.BI "CDKSWINDOW *" "swindow);"
|
|
.TP 15
|
|
.B "chtype **getCDKSwindowContents ("
|
|
.BI "CDKSWINDOW *" "swindow");
|
|
.TP 15
|
|
.B "int injectCDKSwindow ("
|
|
.BI "CDKSWINDOW *" "swindow",
|
|
.BI "chtype " "input");
|
|
.TP 15
|
|
.B "void jumpToLineCDKSwindow ("
|
|
.BI "CDKSWINDOW *" "swindow",
|
|
.BI "int " "line");
|
|
.TP 15
|
|
.B "void loadCDKSwindowInformation ("
|
|
.BI "CDKSWINDOW *" "swindow");
|
|
.TP 15
|
|
.B "void moveCDKSwindow ("
|
|
.BI "CDKSWINDOW *" "swindow",
|
|
.BI "int " "xpos",
|
|
.BI "int " "ypos",
|
|
.BI "boolean " "relative",
|
|
.BI "boolean " "refresh");
|
|
.TP 15
|
|
.B "CDKSWINDOW *newCDKSwindow ("
|
|
.BI "CDKSCREEN *" "cdkscreen",
|
|
.BI "int " "xpos",
|
|
.BI "int " "ypos",
|
|
.BI "int " "height",
|
|
.BI "int " "width",
|
|
.BI "const char *" "title",
|
|
.BI "int " "saveLines",
|
|
.BI "boolean " "box",
|
|
.BI "boolean " "shadow");
|
|
.TP 15
|
|
.B "void positionCDKSwindow ("
|
|
.BI "CDKSWINDOW *" "swindow");
|
|
.TP 15
|
|
.B "void saveCDKSwindowInformation ("
|
|
.BI "CDKSWINDOW *" "swindow");
|
|
.TP 15
|
|
.B "void setCDKSwindow ("
|
|
.BI "CDKSWINDOW *" "swindow",
|
|
.BI "CDK_CONST char **" "info",
|
|
.BI "int " "lines",
|
|
.BI "boolean " "box");
|
|
.TP 15
|
|
.B "void setCDKSwindowBackgroundAttrib ("
|
|
.BI "CDKSWINDOW *" "swindow",
|
|
.BI "chtype " "attribute");
|
|
.TP 15
|
|
.B "void setCDKSwindowBackgroundColor ("
|
|
.BI "CDKSWINDOW *" "swindow",
|
|
.BI "const char * " "color");
|
|
.TP 15
|
|
.B "void setCDKSwindowBox ("
|
|
.BI "CDKSWINDOW *" "swindow,"
|
|
.BI "boolean " "boxWidget);"
|
|
.TP 15
|
|
.B "void setCDKSwindowBoxAttribute ("
|
|
.BI "CDKSWINDOW *" "swindow",
|
|
.BI "chtype " "character");
|
|
.TP 15
|
|
.B "void setCDKSwindowContents ("
|
|
.BI "CDKSWINDOW *" "swindow",
|
|
.BI "char **" "info",
|
|
.BI "int " "lines");
|
|
.TP 15
|
|
.B "void setCDKSwindowHorizontalChar ("
|
|
.BI "CDKSWINDOW *" "swindow",
|
|
.BI "chtype " "character");
|
|
.TP 15
|
|
.B "void setCDKSwindowLLChar ("
|
|
.BI "CDKSWINDOW *" "swindow",
|
|
.BI "chtype " "character");
|
|
.TP 15
|
|
.B "void setCDKSwindowLRChar ("
|
|
.BI "CDKSWINDOW *" "swindow",
|
|
.BI "chtype " "character");
|
|
.TP 15
|
|
.B "void setCDKSwindowPostProcess ("
|
|
.BI "CDKSWINDOW *" "swindow",
|
|
.BI "PROCESSFN " "callback",
|
|
.BI "void * " "data");
|
|
.TP 15
|
|
.B "void setCDKSwindowPreProcess ("
|
|
.BI "CDKSWINDOW *" "swindow",
|
|
.BI "PROCESSFN " "callback",
|
|
.BI "void * " "data");
|
|
.TP 15
|
|
.B "void setCDKSwindowULChar ("
|
|
.BI "CDKSWINDOW *" "swindow",
|
|
.BI "chtype " "character");
|
|
.TP 15
|
|
.B "void setCDKSwindowURChar ("
|
|
.BI "CDKSWINDOW *" "swindow",
|
|
.BI "chtype " "character");
|
|
.TP 15
|
|
.B "void setCDKSwindowVerticalChar ("
|
|
.BI "CDKSWINDOW *" "swindow",
|
|
.BI "chtype " "character");
|
|
.TP 15
|
|
.B "void trimCDKSwindow ("
|
|
.BI "CDKSWINDOW *" "swindow",
|
|
.BI "int " "start",
|
|
.BI "int " "finish");
|
|
.fi
|
|
.SH DESCRIPTION
|
|
The Cdk scrolling window (swindow) widget can be used to display messages.
|
|
The following functions create or manipulate the Cdk swindow box widget.
|
|
.SH AVAILABLE FUNCTIONS
|
|
.TP 5
|
|
.B activateCDKSwindow
|
|
function activates the swindow widget and lets the user interact with the widget.
|
|
.RS
|
|
.bP
|
|
The parameter \fBswindow\fR is a pointer to a non-NULL swindow widget.
|
|
.bP
|
|
If the \fBactions\fR parameter is passed with a non-NULL value, the characters
|
|
in the array will be injected into the widget.
|
|
.IP
|
|
To activate the widget
|
|
interactively pass in a \fINULL\fR pointer for \fBactions\fR.
|
|
.RE
|
|
.IP
|
|
If the character
|
|
entered into this widget is \fIRETURN\fR or \fITAB\fR then this function will
|
|
return 1.
|
|
It will also set the widget data \fIexitType\fR to \fIvNORMAL\fR.
|
|
.IP
|
|
If the character entered into this widget was \fIESCAPE\fR then the widget will
|
|
return a value of -1 and the widget data \fIexitType\fR will be set to
|
|
\fIvESCAPE_HIT\fR.
|
|
.TP 5
|
|
.B addCDKSwindow
|
|
adds information to a scrolling window.
|
|
.RS
|
|
.bP
|
|
The information
|
|
is supplied by the \fBinfo\fR parameter.
|
|
The information is immediately added
|
|
to the scrolling window.
|
|
.bP
|
|
The position of the new information is governed by
|
|
the value of the parameter \fBinsertPosition\fR.
|
|
This parameter may be
|
|
two values: \fITOP\fR or \fIBOTTOM\fR.
|
|
.RE
|
|
.TP 5
|
|
.B cleanCDKSwindow
|
|
clears the information from the window.
|
|
.TP 5
|
|
.B destroyCDKSwindow
|
|
removes the widget from the screen and frees memory the object used.
|
|
.TP 5
|
|
.B drawCDKSwindow
|
|
draws the swindow widget on the screen.
|
|
.IP
|
|
If the \fBbox\fR parameter is true, the widget is drawn with a box.
|
|
.TP 5
|
|
.B dumpCDKSwindow
|
|
saves the contents of the scrolling window into the file
|
|
specified by the \fBfilename\fR parameter.
|
|
It returns -1 on failure,
|
|
and the number of lines saved if the dump was successful.
|
|
.TP 5
|
|
.B eraseCDKSwindow
|
|
removes the widget from the screen.
|
|
This does \fINOT\fR destroy the widget.
|
|
.TP 5
|
|
.B execCDKSwindow
|
|
allows the user to execute a shell command and have the output
|
|
of the shell command direct itself to the scrolling window.
|
|
.RS
|
|
.bP
|
|
The \fBcommand\fR parameter is the command to execute.
|
|
.bP
|
|
The \fBinsertPosition\fR parameter tells where the
|
|
output will be inserted within the scrolling window.
|
|
.RE
|
|
.TP 5
|
|
.B getCDKSwindowBox
|
|
returns true if the widget will be drawn with a box around it.
|
|
.TP 5
|
|
.B getCDKSwindowContents
|
|
returns the contents of the scrolling window.
|
|
.IP
|
|
The parameter \fBlines\fR will be
|
|
set to the number of lines returned.
|
|
.TP 5
|
|
.B injectCDKSwindow
|
|
injects a single character into the widget.
|
|
.RS
|
|
.bP
|
|
The parameter \fBswindow\fR is a pointer to a non-NULL swindow widget.
|
|
.bP
|
|
The parameter \fBcharacter\fR is the character to inject into the widget.
|
|
.RE
|
|
.IP
|
|
The return value and side-effect (setting the widget data \fIexitType\fP)
|
|
depend upon the injected character:
|
|
.RS
|
|
.TP
|
|
\fIRETURN\fP or \fITAB\fR
|
|
the function returns
|
|
1.
|
|
The widget data \fIexitType\fR is set to \fIvNORMAL\fR.
|
|
.TP
|
|
\fIESCAPE\fP
|
|
the function returns
|
|
-1.
|
|
The widget data \fIexitType\fR is set to \fIvESCAPE_HIT\fR.
|
|
.TP
|
|
Otherwise
|
|
unless modified by preprocessing, postprocessing or key bindings,
|
|
the function returns
|
|
-1.
|
|
The widget data \fIexitType\fR is set to \fIvEARLY_EXIT\fR.
|
|
.RE
|
|
.TP 5
|
|
.B jumpToLineCDKSwindow
|
|
moves the scrolling window to the given line.
|
|
.IP
|
|
The parameter \fBline\fR may be an integer or one of the two predefined values
|
|
\fITOP\fR and \fIBOTTOM\fR.
|
|
.TP 5
|
|
.B loadCDKSwindowInformation
|
|
allows the user to load the contents of a file into the scrolling window.
|
|
This function is interactive, and will ask for a filename.
|
|
.TP 5
|
|
.B moveCDKSwindow
|
|
moves the given widget to the given position.
|
|
.RS
|
|
.bP
|
|
The parameters \fBxpos\fR and \fBypos\fR are the new position of the widget.
|
|
.IP
|
|
The parameter \fBxpos\fR may be an integer or one of the pre-defined values
|
|
\fITOP\fR, \fIBOTTOM\fR, and \fICENTER\fR.
|
|
.IP
|
|
The parameter \fBypos\fR may be an integer or one of the pre-defined values \fILEFT\fR,
|
|
\fIRIGHT\fR, and \fICENTER\fR.
|
|
.bP
|
|
The parameter \fBrelative\fR states whether
|
|
the \fBxpos\fR/\fBypos\fR pair is a relative move or an absolute move.
|
|
.IP
|
|
For example,
|
|
if \fBxpos\fR = 1 and \fBypos\fR = 2 and \fBrelative\fR = \fBTRUE\fR,
|
|
then the widget would move one row down and two columns right.
|
|
If the value of \fBrelative\fR was \fBFALSE\fR then the widget would move to the position (1,2).
|
|
.IP
|
|
Do not use the values \fITOP\fR, \fIBOTTOM\fR, \fILEFT\fR,
|
|
\fIRIGHT\fR, or \fICENTER\fR when \fBrelative\fR = \fITRUE\fR
|
|
(weird things may happen).
|
|
.bP
|
|
The final parameter \fBrefresh\fR is a boolean value which
|
|
states whether the widget will get refreshed after the move.
|
|
.RE
|
|
.TP 5
|
|
.B newCDKSwindow
|
|
creates a swindow widget and returns a pointer to it.
|
|
Parameters:
|
|
.RS
|
|
.TP 5
|
|
\fBscreen\fR
|
|
is the screen you wish this widget to be placed in.
|
|
.TP 5
|
|
\fBxpos\fR
|
|
controls the placement of the object along the horizontal axis.
|
|
It may be an integer or one of the pre-defined values
|
|
\fILEFT\fR, \fIRIGHT\fR, and \fICENTER\fR.
|
|
.TP 5
|
|
\fBypos\fR
|
|
controls the placement of the object along the vertical axis.
|
|
It may be an integer or one of the pre-defined values
|
|
\fITOP\fR, \fIBOTTOM\fR, and \fICENTER\fR.
|
|
.TP 5
|
|
\fBheight\fR and
|
|
.TP 5
|
|
\fBwidth\fR
|
|
control the height and width of the widget.
|
|
If you provide a value of zero for either of the height or the width, the
|
|
widget will be created with the full width and height of the screen.
|
|
If you provide
|
|
a negative value, the widget will be created the full height or width minus the
|
|
value provided.
|
|
.TP 5
|
|
\fBtitle\fR
|
|
is the string to display at the top of the widget.
|
|
The title can be more than one line; just provide a carriage
|
|
return character at the line break.
|
|
.TP 5
|
|
\fBsaveLines\fR
|
|
is the number of lines to save before throwing information away.
|
|
.TP 5
|
|
\fBbox\fR
|
|
is true if the widget should be drawn with a box around it.
|
|
.TP 5
|
|
The \fBshadow\fR
|
|
turns the shadow on or off around this widget.
|
|
.RE
|
|
.IP
|
|
If the widget could not be created then a \fINULL\fR pointer is returned.
|
|
.TP 5
|
|
.B positionCDKSwindow
|
|
allows the user to move the widget around the screen via the
|
|
cursor/keypad keys.
|
|
See \fBcdk_position (3)\fR for key bindings.
|
|
.TP 5
|
|
.B saveCDKSwindowInformation
|
|
allows the user to save the contents of the scrolling window into a file.
|
|
This function is interactive, and will ask for a filename.
|
|
.TP 5
|
|
.B setCDKSwindow
|
|
lets the programmer modify certain elements of an existing
|
|
swindow widget.
|
|
.RS
|
|
.bP
|
|
The parameter \fBinfo\fR is a \fIchar **\fR of the information
|
|
to set in the scrolling window; \fBlines\fR is the number of lines being added.
|
|
.bP
|
|
The other parameter names correspond to the same parameter names listed in the
|
|
\fBnewCDKSwindow\fR function.
|
|
.RE
|
|
.TP 5
|
|
.B setCDKSwindowBackgroundAttrib
|
|
sets the background attribute of the widget.
|
|
.IP
|
|
The parameter \fBattribute\fR is a curses attribute, e.g., A_BOLD.
|
|
.TP 5
|
|
.B setCDKSwindowBackgroundColor
|
|
sets the background color of the widget.
|
|
.IP
|
|
The parameter \fBcolor\fR
|
|
is in the format of the Cdk format strings.
|
|
.IP
|
|
See \fBcdk_display (3)\fR.
|
|
.TP 5
|
|
.B setCDKSwindowBox
|
|
sets whether the widget will be drawn with a box around it.
|
|
.TP 5
|
|
.B setCDKSwindowBoxAttribute
|
|
sets the attribute of the box.
|
|
.TP 5
|
|
.B setCDKSwindowContents
|
|
lets the programmer modify certain elements of an existing swindow widget.
|
|
.RS
|
|
.bP
|
|
The parameter \fBinfo\fR is a \fIchar **\fR of the information
|
|
to set in the scrolling window.
|
|
.bP
|
|
\fBlines\fR is the number of lines being added.
|
|
.RE
|
|
.TP 5
|
|
.B setCDKSwindowHorizontalChar
|
|
sets the horizontal drawing character for the box to the given character.
|
|
.TP 5
|
|
.B setCDKSwindowLLChar
|
|
sets the lower left hand corner of the widget's box to the given character.
|
|
.TP 5
|
|
.B setCDKSwindowLRChar
|
|
sets the lower right hand corner of the widget's box to the given character.
|
|
.TP 5
|
|
.B setCDKSwindowPostProcess
|
|
allows the user to have the widget call a function after the
|
|
key has been applied to the widget.
|
|
.RS
|
|
.bP
|
|
The parameter \fBfunction\fR is the callback function.
|
|
.bP
|
|
The parameter \fBdata\fR points to data passed to the callback function.
|
|
.RE
|
|
.IP
|
|
To learn more about post-processing see \fIcdk_process (3)\fR.
|
|
.TP 5
|
|
.B setCDKSwindowPreProcess
|
|
allows the user to have the widget call a function after a key
|
|
is hit and before the key is applied to the widget.
|
|
.RS
|
|
.bP
|
|
The parameter \fBfunction\fR is the callback function.
|
|
.bP
|
|
The parameter \fBdata\fR points to data passed to the callback function.
|
|
.RE
|
|
.IP
|
|
To learn more about pre-processing see \fIcdk_process (3)\fR.
|
|
.TP 5
|
|
.B setCDKSwindowULChar
|
|
sets the upper left hand corner of the widget's box to the given character.
|
|
.TP 5
|
|
.B setCDKSwindowURChar
|
|
sets the upper right hand corner of the widget's box to the given character.
|
|
.TP 5
|
|
.B setCDKSwindowVerticalChar
|
|
sets the vertical drawing character for the box to the given character.
|
|
.TP 5
|
|
.B trimCDKSwindow
|
|
removes information from a scrolling window.
|
|
.IP
|
|
The parameters \fBstart\fR and \fBend\fR state where to start cutting from and where to stop.
|
|
.IP
|
|
The first element in the scrolling window starts at index 0.
|
|
.SH KEY BINDINGS
|
|
When the widget is activated there are several default key bindings which will
|
|
help the user enter or manipulate the information quickly.
|
|
The following table
|
|
outlines the keys and their actions for this widget.
|
|
.LP
|
|
.TS
|
|
center tab(/) box;
|
|
l l
|
|
lw(15) lw(45) .
|
|
\fBKey/Action\fR
|
|
=
|
|
Left Arrow/Scrolls the window left one column.
|
|
Right Arrow/Scrolls the window right one column.
|
|
Up Arrow/Scrolls the window up one row.
|
|
Down Arrow/Scrolls the window down one row.
|
|
_
|
|
Prev Page
|
|
Ctrl-B
|
|
b
|
|
B/Scroll the window backward one page.
|
|
_
|
|
Next Page
|
|
Ctrl-F
|
|
Space
|
|
f
|
|
F/Scroll the window forward one page.
|
|
_
|
|
Home
|
|
|/Scroll the list to the left margin.
|
|
_
|
|
End
|
|
$/Scroll the list to the right margin.
|
|
_
|
|
1
|
|
<
|
|
g/Move to the top of the scrolling window.
|
|
>
|
|
G/Move to the bottom of the scrolling window.
|
|
_
|
|
l
|
|
L/Load a file into the scrolling window.
|
|
_
|
|
s
|
|
S/T{
|
|
Save the contents of the scrolling window into a file.
|
|
T}
|
|
_
|
|
Return/T{
|
|
Set the widget's \fIexitType\fR to \fIvNORMAL\fR, exit the widget and return 1.
|
|
T}
|
|
Tab/T{
|
|
Set the widget's \fIexitType\fR to \fIvNORMAL\fR, exit the widget and return 1.
|
|
T}
|
|
Escape/T{
|
|
Set the widget's \fIexitType\fR to \fIvESCAPE_HIT\fR, exit the widget and return -1.
|
|
T}
|
|
Ctrl-L/Refreshes the screen.
|
|
=
|
|
.TE
|
|
.SH SEE ALSO
|
|
.BR cdk (3),
|
|
.BR cdk_binding (3),
|
|
.BR cdk_display (3),
|
|
.BR cdk_position (3),
|
|
.BR cdk_screen (3)
|