375 lines
9.0 KiB
Groff
375 lines
9.0 KiB
Groff
'\" t
|
|
.\" $Id: cdk_util.3,v 1.10 2016/12/11 01:32:30 tom Exp $
|
|
.de bP
|
|
.IP \(bu 4
|
|
..
|
|
.de XX
|
|
..
|
|
.TH cdk_util 3
|
|
.SH NAME
|
|
.XX CDKgetDirectoryContents
|
|
.XX CDKreadFile
|
|
.XX alignxy
|
|
.XX char2Chtype
|
|
.XX char2DisplayType
|
|
.XX checkForLink
|
|
.XX chtype2String
|
|
.XX deleteCursesWindow
|
|
.XX eraseCursesWindow
|
|
.XX getListIndex
|
|
.XX getString
|
|
.XX justifyString
|
|
.XX mode2Filetype
|
|
.XX moveCursesWindow
|
|
.XX popupDialog
|
|
.XX popupLabel
|
|
.XX popupLabelAttrib
|
|
.XX selectFile
|
|
.XX setWidgetDimension
|
|
.XX stripWhiteSpace
|
|
.XX viewFile
|
|
.XX viewInfo
|
|
cdk_util \- Cdk utility functions
|
|
.SH SYNOPSIS
|
|
.LP
|
|
.B cc
|
|
.RI "[ " "flag" " \|.\|.\|. ] " "file" " \|.\|.\|."
|
|
.B \-lcdk
|
|
.RI "[ " "library" " \|.\|.\|. ]"
|
|
.LP
|
|
#include <cdk.h>
|
|
.nf
|
|
.TP 15
|
|
.B "int CDKgetDirectoryContents ("
|
|
.BI "const char *" "directory",
|
|
.BI "char ***" "list");
|
|
.TP 15
|
|
.B "int CDKreadFile ("
|
|
.BI "const char *" "filename",
|
|
.BI "char ***" "info");
|
|
.TP 15
|
|
.B "void alignxy ("
|
|
.BI "WINDOW *" "window",
|
|
.BI "int *" "xpos",
|
|
.BI "int *" "ypos",
|
|
.BI "int " "boxWidth",
|
|
.BI "int " "boxHeight");
|
|
.TP 15
|
|
.B "chtype *char2Chtype ("
|
|
.BI "const char *" "string",
|
|
.BI "int *" "length",
|
|
.BI "int *" "align");
|
|
.TP 15
|
|
.B "EDisplayType char2DisplayType ("
|
|
.BI "const char *" "string");
|
|
.TP 15
|
|
.B "int checkForLink ("
|
|
.BI "const char *" "line",
|
|
.BI "char *" "filename");
|
|
.TP 15
|
|
.B "char *chtype2String (
|
|
.BI "const chtype *" "string");
|
|
.TP 15
|
|
.B "void deleteCursesWindow ("
|
|
.BI "WINDOW *" "window");
|
|
.TP 15
|
|
.B "void eraseCursesWindow ("
|
|
.BI "WINDOW *" "window");
|
|
.TP 15
|
|
.B "int getListIndex ("
|
|
.BI "CDKSCREEN *" "screen",
|
|
.BI "const char *" "title",
|
|
.BI "CDK_CONST char **" "list",
|
|
.BI "int " "listSize",
|
|
.BI "boolean " "numbers");
|
|
.TP 15
|
|
.B char *getString ("
|
|
.BI "CDKSCREEN *" "screen",
|
|
.BI "const char *" "title",
|
|
.BI "const char *" "label",
|
|
.BI "const char *" "init");
|
|
.TP 15
|
|
.B "int justifyString ("
|
|
.BI "int " "fieldWidth",
|
|
.BI "int " "mesglen",
|
|
.BI "int " "justify");
|
|
.TP 15
|
|
.B "int mode2Filetype ("
|
|
.BI "mode_t " "fileMode");
|
|
.TP 15
|
|
.B "void moveCursesWindow ("
|
|
.BI "WINDOW *" "window",
|
|
.BI "int " "xdiff",
|
|
.BI "int " "ydiff");
|
|
.TP 15
|
|
.B "int popupDialog ("
|
|
.BI "CDKSCREEN *" "screen",
|
|
.BI "CDK_CONST char **" "mesg",
|
|
.BI "int " "mesgCount",
|
|
.BI "CDK_CONST char **" "buttons",
|
|
.BI "int " "buttonCount");
|
|
.TP 15
|
|
.B "void popupLabel ("
|
|
.BI "CDKSCREEN *" "win",
|
|
.BI "CDK_CONST char **" "mesg",
|
|
.BI "int " "count");
|
|
.TP 15
|
|
.B "void popupLabelAttrib ("
|
|
.BI "CDKSCREEN *" "win",
|
|
.BI "CDK_CONST char **" "mesg",
|
|
.BI "int " "count",
|
|
.BI "chtype " "attribute");
|
|
.TP 15
|
|
.B "char *selectFile ("
|
|
.BI "CDKSCREEN *" "screen",
|
|
.BI "const char *" "title");
|
|
.TP 15
|
|
.B "int setWidgetDimension ("
|
|
.BI "int " "parentDim",
|
|
.BI "int " "proposedDim",
|
|
.BI "int " "adjustment");
|
|
.TP 15
|
|
.B "void stripWhiteSpace ("
|
|
.BI "EStripType " "stripType",
|
|
.BI "char *" "string");
|
|
.TP 15
|
|
.B "int viewFile ("
|
|
.BI "CDKSCREEN *" "screen",
|
|
.BI "const char *" "title",
|
|
.BI "const char *" "filename",
|
|
.BI "CDK_CONST char **" "buttons",
|
|
.BI "int " "buttonCount");
|
|
.TP 15
|
|
.B "int viewInfo ("
|
|
.BI "CDKSCREEN *" "screen",
|
|
.BI "const char *" "title",
|
|
.BI "CDK_CONST char **" "info",
|
|
.BI "int " "size",
|
|
.BI "CDK_CONST char **" "buttons",
|
|
.BI "int " "buttonCount",
|
|
.BI "boolean " "interpret");
|
|
.fi
|
|
.SH DESCRIPTION
|
|
These are utility functions that one may use to initialize,
|
|
build or customize widgets.
|
|
.
|
|
.SH AVAILABLE FUNCTIONS
|
|
.TP 5
|
|
.B CDKgetDirectoryContents
|
|
opens and reads the contents of the given directory, filling
|
|
the array \fBlist\fR with the sorted contents of the directory.
|
|
If the directory cannot be opened then it returns a value of -1.
|
|
.TP 5
|
|
.B CDKreadFile
|
|
Read the file \fIfilename\fP,
|
|
load the contents into a dynamically allocated array,
|
|
storing its address via \fIinfo\fP.
|
|
It returns the number of lines
|
|
read if the file could be opened, -1 otherwise.
|
|
.TP 5
|
|
.B alignxy
|
|
Aligns a box on the given \fIwindow\fP with the height and width given.
|
|
See cdk_position (3) for the interpretation of the
|
|
\fIxpos\fP,
|
|
\fIypos\fP,
|
|
\fIboxWidth\fP and
|
|
\fIboxHeight\fP,
|
|
parameters.
|
|
.TP 5
|
|
.B char2Chtype
|
|
Translate a character \fIstring\fP with embedded format markers
|
|
(e.g., "</X/Y>Blah Blah")
|
|
to a null-terminated array of chtype's.
|
|
.RS
|
|
.bP
|
|
The length of the array is stored via the \fIlength\fP parameter.
|
|
.bP
|
|
The \fBalign\fR parameter contains justification information
|
|
(LEFT, CENTER, RIGHT).
|
|
.IP
|
|
The caller is responsible for freeing the result.
|
|
.RE
|
|
.TP 5
|
|
.B char2DisplayType
|
|
Lookup the given name in \fIstring\fP and return the equivalent display type.
|
|
See also cdk_display (3).
|
|
.TP 5
|
|
.B checkForLink
|
|
Check if the given \fIline\fP is of the form
|
|
.RS
|
|
<F=\fIfilename\fP>
|
|
.RE
|
|
.IP
|
|
If so, extract the filename from the line, storing it in the \fIfilename\fP
|
|
buffer (which must hold at least CDK_PATHMAX characters).
|
|
Return nonzero if a filename is extracted.
|
|
.TP 5
|
|
.B chtype2String
|
|
Extract the characters and formatting information
|
|
from a null-terminated array of chtype's \fIstring\fP.
|
|
A dynamically allocated string is returned.
|
|
.TP 5
|
|
.B deleteCursesWindow
|
|
Safely delete a given window,
|
|
i.e., first check if the \fIwindow\fP parameter is nonnull.
|
|
.TP 5
|
|
.B eraseCursesWindow
|
|
Safely erase a given window,
|
|
i.e., first check if the \fIwindow\fP parameter is nonnull.
|
|
.TP 5
|
|
.B getListIndex
|
|
Display a scrollable list of strings in a dialog,
|
|
allow the user to select one.
|
|
Return the index in the list of the value selected.
|
|
.RS
|
|
.bP
|
|
The \fIlist\fP parameter contains the strings to display;
|
|
there are \fIlistSize\fP strings in the list.
|
|
.bP
|
|
If \fInumbers\fP is true, the displayed list items will be numbered.
|
|
.RE
|
|
.TP 5
|
|
.B getString
|
|
pops up an entry widget with
|
|
.RS
|
|
.bP
|
|
a title supplied by the value
|
|
of the \fBtitle\fR parameter,
|
|
.bP
|
|
a label supplied by the \fBlabel\fR parameter,
|
|
and
|
|
.bP
|
|
an initial value supplied by the \fBinitialValue\fR parameter.
|
|
.RE
|
|
.IP
|
|
It returns
|
|
a pointer to the value typed in or NULL if the widget was exited early.
|
|
.TP 5
|
|
.B justifyString
|
|
Given a string length \fImesglen\fP,
|
|
the available field width \fIfieldWidth\fP
|
|
and a justification type \fIjustify\fP,
|
|
return the number of characters by which to shift the string.
|
|
.TP 5
|
|
.B mode2Filetype
|
|
Given a file protection mode \fIfileMode\fP,
|
|
return ignoring the file-type bits,
|
|
i.e., ignoring the corresponding permissions data.
|
|
.TP 5
|
|
.B moveCursesWindow
|
|
Move a given \fIwindow\fP by the amounts in \fIxdiff\fP and \fIydiff\fP.
|
|
.TP 5
|
|
.B popupDialog
|
|
creates a quick pop-up dialog box.
|
|
Pass in
|
|
.RS
|
|
.bP
|
|
the message in the \fBmesg\fR parameter,
|
|
.bP
|
|
the size of the message in the \fBmesgCount\fR parameter,
|
|
.bP
|
|
the button labels in the \fBbuttons\fR parameter and
|
|
.bP
|
|
the number of buttons in the \fBbuttonCount\fR parameter.
|
|
.RE
|
|
.IP
|
|
The dialog box will be centered on the screen.
|
|
.TP 5
|
|
.B popupLabel
|
|
creates a quick pop-up label widget.
|
|
.IP
|
|
The message and the size of
|
|
the message are passed in via the \fBmesg\fR and \fBcount\fR parameters respectively.
|
|
.IP
|
|
The label widget waits until the user hits a character and is centered
|
|
on the screen.
|
|
.TP 5
|
|
.B popupLabelAttrib
|
|
Display a simple dialog with
|
|
a list of \fIcount\fP message strings \fImesg\fP.
|
|
Use the given \fIattribute\fP for the background of the dialog.
|
|
.TP 5
|
|
.B selectFile
|
|
Display a file-selection dialog.
|
|
Return the selected filename, or null if none is selected.
|
|
The caller should free the return-value.
|
|
.TP 5
|
|
.B setWidgetDimension
|
|
This is a helper function used to set the height/width of a widget:
|
|
.RS
|
|
.bP
|
|
If the proposed dimension \fIproposedDim\fP is FULL or zero,
|
|
the return value will be \fIparentDim\fP.
|
|
.bP
|
|
If the proposed dimension \fIproposedDim\fP is positive,
|
|
.RS
|
|
.bP
|
|
and it is larger than \fIparentDim\fP, return \fIproposedDim\fP,
|
|
.bP
|
|
otherwise return \fIproposedDim\fP plus \fIadjustment\fP.
|
|
.RE
|
|
.bP
|
|
If the proposed dimension \fIproposedDim\fP is negative,
|
|
the return value will be \fIparentDim\fP plus \fIproposedDim\fP.
|
|
.bP
|
|
Otherwise, the return value will be \fIproposedDim\fP.
|
|
.RE
|
|
.TP 5
|
|
.B stripWhiteSpace
|
|
Strip whitespace from the front and/or back of the given \fIstring\fP.
|
|
.IP
|
|
The \fIstripType\fP parameter controls the type of stripping done:
|
|
vFRONT, vBACK or vBOTH.
|
|
.TP 5
|
|
.B viewFile
|
|
Read the file specified by \fIfilename\fP and display it in a CDKVIEWER window.
|
|
The \fItitle\fP, \fIbuttons\fP and \fIbuttonCount\fP are applied to the
|
|
CDKVIEWER window.
|
|
.RS
|
|
.bP
|
|
The viewer shows
|
|
the contents of the file supplied by the \fBfilename\fR value.
|
|
.bP
|
|
The buttons on
|
|
the file viewer are supplied by the \fBbuttons\fR parameter.
|
|
.RE
|
|
.IP
|
|
It returns the index of the button selected,
|
|
or -1 if the file does not exist or if the widget was exited early.
|
|
.LP
|
|
.TS
|
|
center tab(/) allbox;
|
|
l l
|
|
l l
|
|
lw15 lw35 .
|
|
\fBStrip_Type/Result\fR
|
|
=
|
|
vFRONT/T{
|
|
This tells the function to remove
|
|
all of the white space from the
|
|
front of the given string.
|
|
T}
|
|
vBACK/T{
|
|
This tells the function to remove
|
|
all of the white space from the
|
|
back of the given string.
|
|
T}
|
|
vBOTH/T{
|
|
This tells the function to remove
|
|
all of the white space from both
|
|
the front and the back of the given string.
|
|
T}
|
|
.TE
|
|
.TP 5
|
|
.B viewInfo
|
|
Display the list of strings in \fIinfo\fP in a CDKVIEWER window.
|
|
The number of strings is given by \fIsize\fP.
|
|
The \fItitle\fP, \fIbuttons\fP and \fIbuttonCount\fP are applied to the
|
|
CDKVIEWER window.
|
|
.
|
|
.SH SEE ALSO
|
|
cdk_dialog (3),
|
|
cdk_display (3),
|
|
cdk_position (3),
|
|
cdk_misc (3).
|