505 lines
13 KiB
Groff
505 lines
13 KiB
Groff
.\" $Id: cdk_template.3,v 1.28 2016/12/11 01:26:36 tom Exp $
|
|
.de bP
|
|
.IP \(bu 4
|
|
..
|
|
.de XX
|
|
..
|
|
.TH cdk_template 3
|
|
.SH NAME
|
|
.XX activateCDKTemplate
|
|
.XX cleanCDKTemplate
|
|
.XX destroyCDKTemplate
|
|
.XX drawCDKTemplate
|
|
.XX eraseCDKTemplate
|
|
.XX getCDKTemplateBox
|
|
.XX getCDKTemplateMin
|
|
.XX getCDKTemplateValue
|
|
.XX injectCDKTemplate
|
|
.XX mixCDKTemplate
|
|
.XX newCDKTemplate
|
|
.XX setCDKTemplate
|
|
.XX setCDKTemplateBackgroundAttrib
|
|
.XX setCDKTemplateBackgroundColor
|
|
.XX setCDKTemplateBox
|
|
.XX setCDKTemplateBoxAttribute
|
|
.XX setCDKTemplateCB
|
|
.XX setCDKTemplateHorizontalChar
|
|
.XX setCDKTemplateLLChar
|
|
.XX setCDKTemplateLRChar
|
|
.XX setCDKTemplateMin
|
|
.XX setCDKTemplatePostProcess
|
|
.XX setCDKTemplatePreProcess
|
|
.XX setCDKTemplateULChar
|
|
.XX setCDKTemplateURChar
|
|
.XX setCDKTemplateValue
|
|
.XX setCDKTemplateVerticalChar
|
|
.XX unmixCDKTemplate
|
|
cdk_template \- a curses template widget.
|
|
.SH SYNOPSIS
|
|
.LP
|
|
.B cc
|
|
.RI "[ " "flag" " \|.\|.\|. ] " "file" " \|.\|.\|."
|
|
.B \-lcdk
|
|
.RI "[ " "library" " \|.\|.\|. ]"
|
|
.LP
|
|
#include <cdk.h>
|
|
.nf
|
|
.TP 15
|
|
.B "char *activateCDKTemplate ("
|
|
.BI "CDKTEMPLATE *" "template",
|
|
.BI "chtype * " "actions");
|
|
.TP 15
|
|
.B "void cleanCDKTemplate ("
|
|
.BI "CDKTEMPLATE *" "template");
|
|
.TP 15
|
|
.B "void destroyCDKTemplate ("
|
|
.BI "CDKTEMPLATE *" "template");
|
|
.TP 15
|
|
.B "void drawCDKTemplate ("
|
|
.BI "CDKTEMPLATE *" "template",
|
|
.BI "boolean " "box");
|
|
.TP 15
|
|
.B "void eraseCDKTemplate ("
|
|
.BI "CDKTEMPLATE *" "template");
|
|
.TP 15
|
|
.B "boolean getCDKTemplateBox ("
|
|
.BI "CDKTEMPLATE *" "template");
|
|
.TP 15
|
|
.B "int getCDKTemplateMin ("
|
|
.BI "CDKTEMPLATE *" "template");
|
|
.TP 15
|
|
.B "char *getCDKTemplateValue ("
|
|
.BI "CDKTEMPLATE *" "template");
|
|
.TP 15
|
|
.B "char *injectCDKTemplate ("
|
|
.BI "CDKTEMPLATE *" "template",
|
|
.BI "chtype " "input");
|
|
.TP 15
|
|
.B "char *mixCDKTemplate ("
|
|
.BI "CDKTEMPLATE *" "template");
|
|
.TP 15
|
|
.B "void moveCDKTemplate ("
|
|
.BI "CDKTEMPLATE *" "template",
|
|
.BI "int " "xpos",
|
|
.BI "int " "ypos",
|
|
.BI "boolean " "relative",
|
|
.BI "boolean " "refresh");
|
|
.TP 15
|
|
.B "CDKTEMPLATE *newCDKTemplate ("
|
|
.BI "CDKSCREEN *" "cdkscreen",
|
|
.BI "int " "xpos",
|
|
.BI "int " "ypos",
|
|
.BI "const char *" "title",
|
|
.BI "const char *" "label",
|
|
.BI "const char *" "plate",
|
|
.BI "const char *" "overlay",
|
|
.BI "boolean " "box",
|
|
.BI "boolean " "shadow");
|
|
.TP 15
|
|
.B "void positionCDKTemplate ("
|
|
.BI "CDKTEMPLATE *" "template");
|
|
.TP 15
|
|
.B "void setCDKTemplate ("
|
|
.BI "CDKTEMPLATE *" "template",
|
|
.BI "const char *" "value",
|
|
.BI "boolean " "box");
|
|
.TP 15
|
|
.B "void setCDKTemplateBackgroundAttrib ("
|
|
.BI "CDKTEMPLATE *" "template",
|
|
.BI "chtype " "attribute");
|
|
.TP 15
|
|
.B "void setCDKTemplateBackgroundColor ("
|
|
.BI "CDKTEMPLATE *" "template",
|
|
.BI "const char * " "color");
|
|
.TP 15
|
|
.B "void setCDKTemplateBox ("
|
|
.BI "CDKTEMPLATE *" "template",
|
|
.BI "boolean " "box");
|
|
.TP 15
|
|
.B "void setCDKTemplateBoxAttribute ("
|
|
.BI "CDKTEMPLATE *" "template",
|
|
.BI "chtype " "character");
|
|
.TP 15
|
|
.B "void setCDKTemplateCB ("
|
|
.BI "CDKTEMPLATE *" "template",
|
|
.BI "TEMPLATECB " "callbackFunction");
|
|
.TP 15
|
|
.B "void setCDKTemplateHorizontalChar ("
|
|
.BI "CDKTEMPLATE *" "template",
|
|
.BI "chtype " "character");
|
|
.TP 15
|
|
.B "void setCDKTemplateLLChar ("
|
|
.BI "CDKTEMPLATE *" "template",
|
|
.BI "chtype " "character");
|
|
.TP 15
|
|
.B "void setCDKTemplateLRChar ("
|
|
.BI "CDKTEMPLATE *" "template",
|
|
.BI "chtype " "character");
|
|
.TP 15
|
|
.B "void setCDKTemplateMin ("
|
|
.BI "CDKTEMPLATE *" "template",
|
|
.BI "int " "minimum");
|
|
.TP 15
|
|
.B "void setCDKTemplatePostProcess ("
|
|
.BI "CDKTEMPLATE *" "template",
|
|
.BI "PROCESSFN " "callback",
|
|
.BI "void * " "data");
|
|
.TP 15
|
|
.B "void setCDKTemplatePreProcess ("
|
|
.BI "CDKTEMPLATE *" "template",
|
|
.BI "PROCESSFN " "callback",
|
|
.BI "void * " "data");
|
|
.TP 15
|
|
.B "void setCDKTemplateULChar ("
|
|
.BI "CDKTEMPLATE *" "template",
|
|
.BI "chtype " "character");
|
|
.TP 15
|
|
.B "void setCDKTemplateURChar ("
|
|
.BI "CDKTEMPLATE *" "template",
|
|
.BI "chtype " "character");
|
|
.TP 15
|
|
.B "void setCDKTemplateValue ("
|
|
.BI "CDKTEMPLATE *" "template",
|
|
.BI "const char *" "value");
|
|
.TP 15
|
|
.B "void setCDKTemplateVerticalChar ("
|
|
.BI "CDKTEMPLATE *" "template",
|
|
.BI "chtype " "character");
|
|
.TP 15
|
|
.B "char *unmixCDKTemplate ("
|
|
.BI "CDKTEMPLATE *" "template",
|
|
.BI "const char *" "string");
|
|
.fi
|
|
.SH DESCRIPTION
|
|
The Cdk template widget creates a template widget which allows a user to type
|
|
information into an entry field with a pre-set field format.
|
|
Typical uses for
|
|
this widget would be a date field or a time field.
|
|
The following are functions
|
|
which create or manipulate the Cdk template box widget.
|
|
.SH AVAILABLE FUNCTIONS
|
|
.TP 5
|
|
.B activateCDKTemplate
|
|
activates the template widget and lets the user interact with the widget.
|
|
.RS
|
|
.bP
|
|
The parameter \fBtemplate\fR is a pointer to a non-NULL template 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
|
|
a \fIchar\ *\fR representing the information typed into the widget and the
|
|
widget data \fIexitType\fR will be set to \fIvNORMAL\fR.
|
|
.IP
|
|
If the character
|
|
entered was \fIESCAPE\fR then the function will return \fINULL\fR pointer and
|
|
the widget data \fIexitType\fR is set to \fIvESCAPE_HIT\fR.
|
|
.TP 5
|
|
.B cleanCDKTemplate
|
|
clears the information from the field.
|
|
.TP 5
|
|
.B destroyCDKTemplate
|
|
removes the widget from the screen and frees any memory the object used.
|
|
.TP 5
|
|
.B drawCDKTemplate
|
|
draws the template widget on the screen.
|
|
If \fBbox\fR is true,
|
|
the widget is drawn with a box.
|
|
.TP 5
|
|
.B eraseCDKTemplate
|
|
removes the widget from the screen.
|
|
This does \fBNOT\fR destroy the widget.
|
|
.TP 5
|
|
.B getCDKTemplateBox
|
|
returns true if the widget will be drawn with a box around it.
|
|
.TP 5
|
|
.B getCDKTemplateMin
|
|
returns the minimum characters that must be entered before the
|
|
widget will exit.
|
|
.TP 5
|
|
.B getCDKTemplateValue
|
|
returns the current value of the widget.
|
|
.TP 5
|
|
.B injectCDKTemplate
|
|
injects a single character into the widget.
|
|
.RS
|
|
.bP
|
|
The parameter \fBtemplate\fR is a pointer to a non-NULL template 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
|
|
a \fIchar\ *\fR representing the information typed into the widget.
|
|
The widget data \fIexitType\fR is set to \fIvNORMAL\fR.
|
|
.TP
|
|
\fIESCAPE\fP
|
|
the function returns
|
|
a \fINULL\fR pointer.
|
|
The widget data \fIexitType\fR is set to \fIvESCAPE_HIT\fR.
|
|
.TP
|
|
Otherwise
|
|
unless modified by preprocessing, postprocessing or key bindings,
|
|
the function returns
|
|
a \fINULL\fR pointer.
|
|
The widget data \fIexitType\fR is set to \fIvEARLY_EXIT\fR.
|
|
.RE
|
|
.TP 5
|
|
.B mixCDKTemplate
|
|
returns a \fIchar*\fR pointer to the field value and the plate.
|
|
.TP 5
|
|
.B moveCDKTemplate
|
|
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 is an integer or one of the predefined 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 be repainted after the move.
|
|
.RE
|
|
.TP 5
|
|
.B newCDKTemplate
|
|
creates a template widget, returning 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
|
|
\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
|
|
\fBlabel\fR
|
|
is the string to display in the label of the template field.
|
|
.TP 5
|
|
\fBplate\fR
|
|
defines the character to allow at each position in the template field.
|
|
This is done by creating a character plate by using
|
|
special format character to tell the template widget what type of character
|
|
is allowed where in the template widget.
|
|
The following table lists the format types.
|
|
.LP
|
|
.TS
|
|
center tab(/);
|
|
l
|
|
l l
|
|
lw15 lw35 .
|
|
\fBPlate_Character/Effect\fR
|
|
=
|
|
#/Accepts an integer.
|
|
A/Accepts an alphabetic value.
|
|
C/T{
|
|
Accepts an alphabetic value.
|
|
Automatically converts the character to upper case.
|
|
T}
|
|
c/T{
|
|
Accepts an alphabetic value.
|
|
Automatically converts the character to lower case.
|
|
T}
|
|
M/T{
|
|
Accepts alphanumeric characters.
|
|
T}
|
|
X/T{
|
|
Accepts alphanumeric characters.
|
|
Automatically converts the character to upper case.
|
|
T}
|
|
x/T{
|
|
Accepts alphanumeric characters.
|
|
Automatically converts the character to upper case.
|
|
T}
|
|
Anything else/T{
|
|
Ignored and assumed a non-editable position.
|
|
T}
|
|
=
|
|
.TE
|
|
.TP 5
|
|
\fBoverlay\fR
|
|
is the overlay of the template field.
|
|
If the field
|
|
needs some sort of overlay, this parameter supplies this.
|
|
A date field could
|
|
have YY/MM/DD, the overlay parameter would display YY/MM/DD on an empty template field.
|
|
.TP 5
|
|
\fBbox\fR
|
|
is true if the widget should be drawn with a box around it.
|
|
.TP 5
|
|
\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 positionCDKTemplate
|
|
allows the user to move the widget around the screen via the
|
|
single keystroke commands.
|
|
See \fBcdk_position (3)\fR for key bindings.
|
|
.TP 5
|
|
.B setCDKTemplate
|
|
lets the programmer modify certain elements of an existing
|
|
template widget.
|
|
.IP
|
|
The parameter names correspond to the same parameter names
|
|
listed in the \fBnewCDKTemplate\fR function.
|
|
.TP 5
|
|
.B setCDKTemplateBackgroundAttrib
|
|
sets the background attribute of the widget.
|
|
.IP
|
|
The parameter \fBattribute\fR is a curses attribute, e.g., A_BOLD.
|
|
.TP 5
|
|
.B setCDKTemplateBackgroundColor
|
|
sets the background color of the widget.
|
|
.IP
|
|
The parameter \fBcolor\fR
|
|
is in the format of the Cdk format strings.
|
|
.IP
|
|
For more information, see the \fIcdk_display (3)\fR.
|
|
.TP 5
|
|
.B setCDKTemplateBox
|
|
sets a flag, true if the widget will be drawn with a box around it.
|
|
.TP 5
|
|
.B setCDKTemplateBoxAttribute
|
|
sets the attribute of the box.
|
|
.TP 5
|
|
.B setCDKTemplateCB
|
|
allows the programmer to set a different widget input handler.
|
|
.IP
|
|
The parameter \fBcallbackFunction\fR is of type \fITEMPLATECB\fR.
|
|
.IP
|
|
The default input handler is \fICDKTemplateCallBack\fR.
|
|
.TP 5
|
|
.B setCDKTemplateHorizontalChar
|
|
sets the horizontal drawing character for the box to
|
|
the given character.
|
|
.TP 5
|
|
.B setCDKTemplateLLChar
|
|
sets the lower left hand corner of the widget's box to
|
|
the given character.
|
|
.TP 5
|
|
.B setCDKTemplateLRChar
|
|
sets the lower right hand corner of the widget's box to
|
|
the given character.
|
|
.TP 5
|
|
.B setCDKTemplateMin
|
|
sets the minimum number of characters that must be entered
|
|
before the widget will exit.
|
|
.TP 5
|
|
.B setCDKTemplatePostProcess
|
|
allows the user to have the widget call a function after the
|
|
key has been applied to the widget.
|
|
To learn more about post-processing see \fIcdk_process\fR (3).
|
|
.TP 5
|
|
.B setCDKTemplatePreProcess
|
|
allows the user to have the widget call a function after a key
|
|
is hit and before the key is applied to the widget.
|
|
To learn more about preprocessing see \fIcdk_process\fR (3).
|
|
.TP 5
|
|
.B setCDKTemplateULChar
|
|
sets the upper left hand corner of the widget's box to
|
|
the given character.
|
|
.TP 5
|
|
.B setCDKTemplateURChar
|
|
sets the upper right hand corner of the widget's box to
|
|
the given character.
|
|
.TP 5
|
|
.B setCDKTemplateValue
|
|
sets a value in the widget.
|
|
.TP 5
|
|
.B setCDKTemplateVerticalChar
|
|
sets the vertical drawing character for the box to
|
|
the given character.
|
|
.TP 5
|
|
.B unmixCDKTemplate
|
|
returns a \fIchar*\fR pointer to the field value without any
|
|
plate characters.
|
|
.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.
|
|
.TS
|
|
center tab(/) allbox;
|
|
l l
|
|
l l
|
|
lw15 lw35 .
|
|
\fBKey/Action\fR
|
|
=
|
|
Delete/T{
|
|
Deletes the character at the cursor.
|
|
T}
|
|
Backspace/T{
|
|
Deletes the character before cursor, moves cursor left.
|
|
T}
|
|
Ctrl-P/T{
|
|
Pastes whatever is in the paste buffer, into the widget.
|
|
T}
|
|
Ctrl-K/T{
|
|
Cuts the contents from the widget and saves a copy in the paste buffer.
|
|
T}
|
|
Ctrl-T/T{
|
|
Copies the contents of the widget into the paste buffer.
|
|
T}
|
|
Ctrl-E/T{
|
|
Erases the contents of the widget.
|
|
T}
|
|
Return/T{
|
|
Exits the widget and returns a \fIchar*\fR representing the information which was typed into the field.
|
|
It also sets the widget data \fIexitType\fR to \fIvNORMAL\fR.
|
|
T}
|
|
Tab/T{
|
|
Exits the widget and returns a \fIchar*\fR representing the information which was typed into the field.
|
|
It also sets the widget data \fIexitType\fR to \fIvNORMAL\fR.
|
|
T}
|
|
Escape/T{
|
|
Exits the widget and returns a \fINULL\fR pointer.
|
|
It also sets the widget data \fIexitType\fR to \fIvESCAPE_HIT\fR.
|
|
T}
|
|
Ctrl-L/Refreshes the screen.
|
|
.TE
|
|
.SH SEE ALSO
|
|
.BR cdk (3),
|
|
.BR cdk_binding (3),
|
|
.BR cdk_display (3),
|
|
.BR cdk_screen (3)
|