'\" t
.\" $Id: cdk_util.3,v 1.4 2005/04/24 18:10:50 tom Exp $
.TH cdk_util 3
.SH NAME
Beep,
CDKallocStrings,
CDKcountStrings,
CDKfreeChtypes,
CDKfreeStrings,
CDKgetDirectoryContents,
CDKreadFile,
CDKsplitString,
alignxy,
baseName,
ceilCDK,
char2Chtype,
char2DisplayType,
checkForLink,
chlen,
chstrncpy,
chtype2Char,
chtype2String,
cleanChar,
cleanChtype,
cmpStrChstr,
copyChar,
copyChtype,
deleteCursesWindow,
dirName,
eraseCursesWindow,
floorCDK,
freeChar,
freeCharList,
freeChtype,
freeChtypeList,
getListIndex,
getString,
intlen,
justifyString,
mode2Char,
mode2Filetype,
moveCursesWindow,
popupDialog,
popupLabel,
popupLabelAttrib,
searchList,
selectFile,
setWidgetDimension,
sortList,
stripWhiteSpace,
viewFile,
viewInfo \- Cdk utility functions
.SH SYNOPSIS
.LP
.B cc
.RI "[ " "flag" " \|.\|.\|. ] " "file" " \|.\|.\|."
.B \-lcdk
.RI "[ " "library" " \|.\|.\|. ]"
.LP
#include <cdk.h>
.nf
.TP 15
.B "void Beep(void);"
.TP 15
.B "unsigned CDKallocStrings("
.BI "char ***" "list"/,
.BI "char *" "item"/,
.BI "unsigned " "length"/,
.BI "unsigned " "used"/);
.TP 15
.B "unsigned CDKcountStrings("
.BI "char **" list");
.TP 15
.B "void CDKfreeChtypes("
.BI "chtype **" "list");
.TP 15
.B "void CDKfreeStrings("
.BI "char **" "list");
.TP 15
.B "int CDKgetDirectoryContents ("
.BI "char *" "directory",
.BI "char ***" "list");
.TP 15
.B "int CDKreadFile ("
.BI "char *" "filename",
.BI "char ***" "info");
.TP 15
.B "char **CDKsplitString("
.BI "char *" "string",
.BI "int " "separator");
.TP 15
.B "void alignxy ("
.BI "WINDOW *" "window",
.BI "int *" "xpos",
.BI "int *" "ypos",
.BI "int " "boxWidth",
.BI "int " "boxHeight");
.TP 15
.B "char *baseName ("
.BI "char *" "filename");
.TP 15
.B "int ceilCDK("
.BI "double" "value");
.TP 15
.B "chtype *char2Chtype ("
.BI "char *" "string",
.BI "int *" "length",
.BI "int *" "align");
.TP 15
.B "EDisplayType char2DisplayType ("
.BI "char *" "string");
.TP 15
.B "int checkForLink ("
.BI "char *" "line",
.BI "char *" "filename");
.TP 15
.B "int chlen ("
.BI "chtype *" "string");
.TP 15
.B "void chstrncpy(
.BI "char *" "dest",
.BI "chtype *" "src",
.BI "int " "maxcount");
.TP 15
.B "char *chtype2Char ("
.BI "chtype *" "string");
.TP 15
.B "char *chtype2String (
.BI "chtype *" "string");
.TP 15
.B "void cleanChar ("
.BI "char *" "string",
.BI "int " "length",
.BI "char " "character");
.TP 15
.B "void cleanChtype ("
.BI "chtype *" "string",
.BI "int " "length",
.BI "chtype" "character");
.TP 15
.B "int cmpStrChstr("
.BI "char *" "str",
.BI "chtype *" "chstr");
.TP 15
.B "char *copyChar ("
.BI "char *" "string");
.TP 15
.B "chtype *copyChtype ("
.BI "chtype *" "string");
.TP 15
.B "void deleteCursesWindow ("
.BI "WINDOW *" "window");
.TP 15
.B "char *dirName ("
.BI "char *" "filename");
.TP 15
.B "void eraseCursesWindow ("
.BI "WINDOW *" "window");
.TP 15
.B "int floorCDK("
.BI "double " "value");
.TP 15
.B "void freeChar ("
.BI "char *" "string");
.TP 15
.B "void freeCharList ("
.BI "char **" "list",
.BI "unsigned " "size");
.TP 15
.B "void freeChtype (
.BI "chtype *" "string");
.TP 15
.B void freeChtypeList ("
.BI "chtype **" "list",
.BI "unsigned " "size");
.TP 15
.B "int getListIndex ("
.BI "CDKSCREEN *" "screen",
.BI "char *" "title",
.BI "char **" "list",
.BI "int " "listSize",
.BI "boolean " "numbers");
.TP 15
.B char *getString ("
.BI "CDKSCREEN *" "screen",
.BI "char *" "title",
.BI "char *" "label",
.BI "char *" "init");
.TP 15
.B "int intlen ("
.BI "int " "value");
.TP 15
.B "int justifyString ("
.BI "int " "fieldWidth",
.BI "int " "mesglen",
.BI "int " "justify");
.TP 15
.B "int mode2Char ("
.BI "char *" "string",
.BI "mode_t " "fileMode");
.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 "char **" "mesg",
.BI "int " "mesgCount",
.BI "char **" "buttons",
.BI "int " "buttonCount");
.TP 15
.B "void popupLabel ("
.BI "CDKSCREEN *" "win",
.BI "char **" "mesg",
.BI "int " "count");
.TP 15
.B "void popupLabelAttrib ("
.BI "CDKSCREEN *" "win",
.BI "char **" "mesg",
.BI "int " "count",
.BI "chtype " "attribute");
.TP 15
.B "int searchList ("
.BI "char **" "list",
.BI "int " "listSize",
.BI "char *" "pattern");
.TP 15
.B "char *selectFile ("
.BI "CDKSCREEN *" "screen",
.BI "char *" "title");
.TP 15
.B "int setWidgetDimension ("
.BI "int " "parentDim",
.BI "int " "proposedDim",
.BI "int " "adjustment");
.TP 15
.B "void sortList ("
.BI "char *" "list" [],
.BI "int " "length");
.TP 15
.B "void stripWhiteSpace ("
.BI "EStripType " "stripType",
.BI "char *" "string");
.TP 15
.B "int viewFile ("
.BI "CDKSCREEN *" "screen",
.BI "char *" "title",
.BI "char *" "filename",
.BI "char **" "buttons",
.BI "int " "buttonCount");
.TP 15
.B "int viewInfo ("
.BI "CDKSCREEN *" "screen",
.BI "char *" "title",
.BI "char **" "info",
.BI "int " "size",
.BI "char **" "buttons",
.BI "int " "buttonCount",
.BI "boolean " "interpret");
.fi
.SH DESCRIPTION
.
.SH AVAILABLE FUNCTIONS
.TP 5
.B Beep
This beeps at the user.
The standard curses beep() does not
flush the stream, so it will only beep until a force is made.
This forces a flush after issuing the beep command.
.TP 5
.B CDKallocStrings
Add a new string \fIitem\fP to a \fIlist\fP.
Keep a null pointer on the end so one may use
\fBCDKfreeStrings()\fP to deallocate the whole list.
The caller is responsible for updating the \fIlength\fP of the list.
The return value is the updated number of chars \fIused\fP.
.TP 5
.B CDKcountStrings
Count the number of items in a null-terminated \fIlist\fP of character strings.
Return the count.
.TP 5
.B CDKfreeChtypes
Free a \fIlist\fP of chtype-strings which is terminated by a null pointer.
.TP 5
.B CDKfreeStrings
Free a \fIlist\fP of character strings which is terminated by a null pointer.
.TP 5
.B CDKgetDirectoryContents
Open the given \fIdirectory\fP and reads in the contents.
Store result in \fIlist\fP and return the number of elements found.
.TP 5
.B CDKreadFile
Read the file \fIfilename\fP,
load the contents into a dynamically allocated array,
storing its address via \fIinfo\fP
and return the number of lines read.
.TP 5
.B CDKsplitString
Split the \fIstring\fP at each occurrence of \fIseparator\fP,
returning a pointer to a dynamically allocated array of the pieces.
The original \fIstring\fP is unmodified.
.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 baseName
Return the basename of the given \fIfilename\fP.
The result should be freed by the caller.
.TP 5
.B ceilCDK
Return an integer like the math library \fBceil()\fP, which returns a double.
.TP 5
.B char2Chtype
Translate a character \fIstring\fP with embedded format markers
to a null-terminated array of chtype's.
The length of the array is stored via the \fIlength\fP parameter.
The alignment (LEFT, CENTER, RIGHT) is stored via the \fIalign\fP parameter.
.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 chlen
Returns the length of the (null-terminated) \fIstring\fP of chtype's.
.TP 5
.B chstrncpy
Extract the characters from a null-terminated array of chtype's \fIsrc\fP.
The size of the destination \fIdest\fP is given in \fImaxcount\fP.
.TP 5
.B chtype2Char
Extract the characters from a null-terminated array of chtype's \fIstring\fP.
A dynamically allocated string is returned.
.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 cleanChar
Set the characters in \fIstring\fP to the given \fIcharacter\fP.
The length of \fIstring\fP is given by \fIlength\fP.
.TP 5
.B cleanChtype
Set the chtype's in \fIstring\fP to the given \fIcharacter\fP.
The length of \fIstring\fP is given by \fIlength\fP.
.TP 5
.B cmpStrChstr
Compare a char string \fIstr\fP to a chtype string \fIchstr\fP.
Return -1, 0 or 1 according to whether \fIstr\fP is less than, equal to
to greater than \fIchstr\fP.
.TP 5
.B copyChar
Copy the given character string (like strdup).
.TP 5
.B copyChtype,
Copy the given chtype string (analogous to strdup).
.TP 5
.B deleteCursesWindow
Safely delete a given window,
i.e., first check if the \fIwindow\fP parameter is nonnull.
.TP 5
.B dirName
Returns the directory for the given \fIfilename\fP,
i.e., the part before the * last slash.
The return value should be freed by the caller.
.TP 5
.B eraseCursesWindow
Safely erase a given window,
i.e., first check if the \fIwindow\fP parameter is nonnull.
.TP 5
.B floorCDK
Return an integer like the math function floor(), which returns a double.
.TP 5
.B freeChar
Free the memory used by the given \fIstring\fP.
.TP 5
.B freeCharList
Free the memory used by the given \fIlist\fP of strings.
The number of strings to free is given by \fIsize\fP.
.TP 5
.B freeChtype
Free frees the memory used by the given chtype \fIstring\fP.
.TP 5
.B freeChtypeList
Free the memory used by the given \fIlist\fP of chtype strings.
The number of strings to free is given by \fIsize\fP.
.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.
The \fIlist\fP parameter contains the strings to display;
there are \fIlistSize\fP strings in the list.
If \fInumbers\fP is true, the displayed list items will be numbered.
.TP 5
.B getString
Display a simple dialog containing a prompt \fIlabel\fP and
initial value \fIinit\fP for the user's response.
Return the response string.
.TP 5
.B intlen
Return the number of characters which are required to represent the given
integer \fIvalue\fP.
.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 mode2Char
Given a file protection mode \fIfileMode\fP,
store a printable version of the permissions in \fIstring\fP.
Return the corresponding permissions data,
i.e., ignoring the file-type bits.
.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
Display a simple dialog with
a list of \fImesgCount\fP message strings \fImesg\fP.
At the bottom of the dialog, display \fIbuttonCount\fP buttons.
.TP 5
.B popupLabel
Display a simple dialog with
a list of \fIcount\fP message strings \fImesg\fP.
.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 searchList
Search the given \fIlist\fP of \fIlistSize\fP strings
for a subset of a word \fIpattern\fP in the given list.
Return the index in the list if it is found, or -1 if not found.
.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
.TP 3
-
If the proposed dimension \fIproposedDim\fP is FULL or zero,
the return value will be \fIparentDim\fP.
.TP 3
-
If the proposed dimension \fIproposedDim\fP is positive,
.RS
.TP 3
-
and it is larger than \fIparentDim\fP, return \fIproposedDim\fP,
.TP 3
-
otherwise return \fIproposedDim\fP plus \fIadjustment\fP.
.RE
.TP 3
-
If the proposed dimension \fIproposedDim\fP is negative,
the return value will be \fIparentDim\fP plus \fIproposedDim\fP.
.TP 3
-
Otherwise, the return value will be \fIproposedDim\fP.
.RE
.TP 5
.B sortList
This is a wrapper for qsort,
used to sort the \fIlist\fP of strings.
The number of strings in \fIlist\fP is given by \fIlength\fP.
.TP 5
.B stripWhiteSpace
Strip whitespace from the front and/or back of the given \fIstring\fP.
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.
.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).