'\" t
.\" $Id: cdk_binding.3,v 1.27 2019/02/19 10:19:12 tom Exp $
.de XX
..
.TH cdk_binding 3
.SH NAME
.XX bindCDKObject
.XX checkCDKObjectBind
.XX cleanCDKObjectBindings
.XX unbindCDKObject
.XX getcCDKObject
.XX getchCDKObject
cdk_binding - \fBCurses Development Kit\fR Character Binding Capabilities.
.LP
.SH SYNOPSIS
.LP
.B cc
.RI "[ " "flag" " \|.\|.\|. ] " "file" " \|.\|.\|."
.B \-lcdk
.RI "[ " "library" " \|.\|.\|. ]"
.LP
.nf
#include <cdk.h>
.TP 15
.B "void bindCDKObject ("
.BI "EObjectType " "cdkType",
.BI "void *" "object",
.BI "chtype " "key",
.BI "BINDFN " "function",
.BI "void *" "data");
.TP 15
.B "int checkCDKObjectBind ("
.BI "EObjectType " "cdkType",
.BI "void *" "object",
.BI "chtype " "key");
.TP 15
.B "void cleanCDKObjectBindings ("
.BI "EObjectType " "cdkType",
.BI "void *" "object");
.TP 15
.B "bool isCDKObjectBind ("
.BI "EObjectType " "cdkType",
.BI "void *" "object",
.BI "chtype " "key");
.TP 15
.B "void unbindCDKObject ("
.BI "EObjectType " "cdkType",
.BI "void *" "object",
.BI "chtype " "key");
.TP 15
.B "int getcCDKObject ("
.BI "CDKOBJS *" "object");
.TP 15
.B "int getchCDKObject ("
.BI "CDKOBJS *" "object",
.BI "boolean *" "functionKey");
.fi
.SH DESCRIPTION
Cdk has the ability to create user definable key bindings.
This ability makes
Cdk more dynamic and usable for a wide variety of tasks.
The following section
outlines the binding functions, their use, and their purpose.
.TP 5
.B bindCDKObject
creates a key binding between a specific Cdk widget (\fBobject\fR)
given key (\fBkey\fR).
The parameter \fBcdkType\fR is of type \fIEObjectType\fR
which is one of the following values.
.LP
.TS
center tab(/);
l
l l
lw10 lw20 lw 20 .
\fBEObjectType_Value/Corresponding_Widget/Widget_Manual_Page\fP
=
vALPHALIST/Alphalist Widget/cdk_alphalist (3)
vBUTTON/Button Widget/cdk_button (3)
vBUTTONBOX/Buttonbox Widget/cdk_buttonbox (3)
vCALENDAR/Calendar Widget/cdk_calendar (3)
vDIALOG/Dialog Widget/cdk_dialog (3)
vDSCALE/DoubleFloat Widget/cdk_dscale (3)
vENTRY/Entry Widget/cdk_entry (3)
vFSCALE/Floating Scale Widget/cdk_fscale (3)
vFSELECT/File Selector Widget/cdk_fselect (3)
vFSLIDER/Floating Slider Widget/cdk_fslider (3)
vGRAPH/Graph Widget/cdk_graph (3)
vHISTOGRAM/Histogram Widget/cdk_histogram (3)
vITEMLIST/Item List Widget/cdk_itemlist (3)
vLABEL/Label Widget/cdk_label (3)
vMARQUEE/Marquee Widget/cdk_marquee (3)
vMATRIX/Matrix Widget/cdk_matrix (3)
vMENTRY/Multiple Line Entry Widget/cdk_mentry (3)
vMENU/Menu Widget/cdk_menu (3)
vRADIO/Radio List Widget/cdk_radio (3)
vSCALE/Integer Scale Widget/cdk_scale (3)
vSCROLL/Scrolling List Widget/cdk_scroll (3)
vSELECTION/Selection List Widget/cdk_selection (3)
vSLIDER/Slider Widget/cdk_slider (3)
vSWINDOW/Scrolling Window Widget/cdk_swindow (3)
vTEMPLATE/Template Entry Widget/cdk_template (3)
vUSCALE/Unsigned Scale Widget/cdk_uscale (3)
vUSLIDER/Unsigned Slider Widget/cdk_uslider (3)
vVIEWER/Viewer Widget/cdk_viewer (3)
=
.TE
.RS 3
The parameter \fBfunction\fR is the callback function.
The parameter \fBdata\fR points to data passed to the callback function.
The parameter \fBkey\fR is the key hit which triggered this callback.
.RE
.TP 5
.B checkCDKObjectBind
check to see if a binding for the given \fBkey\fP exists.
If it does,
Cdk runs the associated command and returns its value,
normally TRUE. 
If no binding exists, return FALSE.
.IP
The widgets which accept input, e.g., via "inject" methods,
use this to check if the injected character is bound to a function.
If that returns TRUE, the widget may update its \fIexitType\fP value:
if \fIearlyExit\fP value is set
(not equal to vNEVER_ACTIVATED),
the widget sets \fIexitType\fP to that value.
.TP 5
.B cleanCDKObjectBindings
removes all user defined key bindings from the given widget.
.TP 5
.B isCDKObjectBind
check to see if a binding for the given \fBkey\fP exists.
If it does return TRUE.
If no binding exists, return FALSE.
.TP 5
.B unbindCDKObject
removes a specific binding to an object.
The parameter are
the same as for \fBbindCDKObject\fR.
.TP 5
.B getcCDKObject
reads a keycode from the given widget.
This is deprecated: use \fBgetchCDKObject\fP.
.TP 5
.B getchCDKObject
reads a keycode from the given widget, and
sets a flag via the \fIfunctionKey\fP parameter
to indicate if the result is a function key.
The \fIfunctionKey\fP parameter may be null;
the keycode is returned whether or not the flag can be set.
.IP
If the keycode has been bound to the special function \fBgetcCDKBind\fP,
then it will be translated to the value which was given for the binding data.
Otherwise, a few special cases are performed:
.TS
center tab(/) box;
l l
lw25 lw25 .
\fBKey/Result\fR
=
CTRL-A/KEY_HOME
CTRL-B/KEY_LEFT
CTRL-E/KEY_END
CTRL-F/KEY_RIGHT
CTRL-N/tab
CTRL-P/KEY_BTAB
DEL/KEY_DC
backspace/KEY_BACKSPACE
carriage return/KEY_ENTER
newline/KEY_ENTER
.TE
.PP
All of the widgets use \fBgetchCDKObject\fP internally for consistency.
.SH EXAMPLE
To help demonstrate how to use the key bindings I will demonstrate a simple
dialog box widget with help for each button.
The following code segment creates
a dialog box and a callback function named \fIdialogHelpCB\fR.
.LP
.nf
.ce
\fI________________________________________\fR
.LP
.ta 9 17 25 33 41
#include <cdk.h>

#ifdef HAVE_XCURSES
char *XCursesProgramName="bind_ex";
#endif

static int dialogHelpCB (EObjectType cdktype GCC_UNUSED, void *object, void *clientData GCC_UNUSED, chtype key GCC_UNUSED)
{
   CDKDIALOG *dialog = (CDKDIALOG *)object;
   char *mesg[5];

   /* Check which button we are on. */
   if (dialog->currentButton == 0)
   {
      mesg[0] = "<C></U>Help for </U>Who<!U>.";
      mesg[1] = "<C>When this button is picked the name of the current";
      mesg[2] = "<C>user is displayed on the screen in a popup window.";
      popupLabel (ScreenOf(dialog), mesg, 3);
   }
   else if (dialog->currentButton == 1)
   {
      mesg[0] = "<C></U>Help for </U>Time<!U>.";
      mesg[1] = "<C>When this button is picked the current time is";
      mesg[2] = "<C>displayed on the screen in a popup window.";
      popupLabel (ScreenOf(dialog), mesg, 3);
   }
   else if (dialog->currentButton == 2)
   {
      mesg[0] = "<C></U>Help for </U>Date<!U>.";
      mesg[1] = "<C>When this button is picked the current date is";
      mesg[2] = "<C>displayed on the screen in a popup window.";
      popupLabel (ScreenOf(dialog), mesg, 3);
   }
   else if (dialog->currentButton == 3)
   {
      mesg[0] = "<C></U>Help for </U>Quit<!U>.";
      mesg[1] = "<C>When this button is picked the dialog box is exited.";
      popupLabel (ScreenOf(dialog), mesg, 2);
   }
   return (FALSE);
}

int main (void)
{
   /* Declare variables. */
   CDKSCREEN	*cdkscreen;
   CDKDIALOG	*question;
   char		*buttons[40];
   char		*message[40], *info[5], *loginName;
   char		temp[256];
   int		selection;
   time_t	clck;
   struct tm	*currentTime;

   cdkscreen = initCDKScreen (NULL);

   /* Start color. */
   initCDKColor();

   /* Set up the dialog box. */
   message[0] = "<C></U>Simple Command Interface";
   message[1] = "Pick the command you wish to run.";
   message[2] = "<C>Press </R>?<!R> for help.";
   buttons[0] = "Who";
   buttons[1] = "Time";
   buttons[2] = "Date";
   buttons[3] = "Quit";

   /* Create the dialog box. */
   question	= newCDKDialog (cdkscreen, CENTER, CENTER,
				message, 3, buttons, 4, A_REVERSE,
				TRUE, TRUE, FALSE);

   /* Check if we got a null value back. */
   if (question == (CDKDIALOG *)0)
   {
      destroyCDKScreen (cdkscreen);

      /* End curses... */
      endCDK();

      /* Spit out a message. */
      printf ("Oops. Can't seem to create the dialog box. Is the window too small?\\n");
      exit (1);
   }

   /* Create the key binding. */
   bindCDKObject (vDIALOG, question, '?', dialogHelpCB, 0);

   /* Activate the dialog box. */
   selection = 0;
   while (selection != 3)
   {
      /* Get the users button selection. */
      selection = activateCDKDialog (question, (chtype *)0);

      /* Check the results. */
      if (selection == 0)
      {
	 /* Get the users login name. */
	 info[0] = "<C>     </U>Login Name<!U>     ";
	 loginName = getlogin();
	 if (loginName == (char *)0)
	 {
	    strcpy (temp, "<C></R>Unknown");
	 }
	 else
	 {
	     sprintf (temp, "<C><%s>", loginName);
	 }
	 info[1] = copyChar (temp);
	 popupLabel (ScreenOf(question), info, 2);
	 freeChar (info[1]);
      }
      else if (selection == 1)
      {
	 /* Print out the time. */
	 time(&clck);
	 currentTime = localtime(&clck);
	 sprintf (temp, "<C>%d:%d:%d", currentTime->tm_hour,
					currentTime->tm_min,
					currentTime->tm_sec);
	 info[0] = "<C>   </U>Current Time<!U>   ";
	 info[1] = copyChar (temp);
	 popupLabel (ScreenOf(question), info, 2);
	 freeChar (info[1]);
      }
      else if (selection == 2)
      {
	 /* Print out the date. */
	 time(&clck);
	 currentTime = localtime(&clck);
	 sprintf (temp, "<C>%d/%d/%02d", currentTime->tm_mday,
					currentTime->tm_mon,
					currentTime->tm_year % 100);
	 info[0] = "<C>   </U>Current Date<!U>   ";
	 info[1] = copyChar (temp);
	 popupLabel (ScreenOf(question), info, 2);
	 freeChar (info[1]);
      }
   }

   /* Clean up. */
   destroyCDKDialog (question);
   destroyCDKScreen (cdkscreen);
   endCDK();
   exit (0);
}
.fi
.ce
\fI________________________________________\fR

.SH SEE ALSO
.BR cdk (3),
.BR cdk_display (3),
.BR cdk_screen (3)