cdk_binding - Man Page

Curses Development Kit Character Binding Capabilities.

Synopsis

cc [ flag ... ] file ... -lcdk [ library ... ]

#include <cdk.h>
    void bindCDKObject (
EObjectType cdkType,
void *object,
chtype key,
BINDFN function,
void *data);
    int checkCDKObjectBind (
EObjectType cdkType,
void *object,
chtype key);
    void cleanCDKObjectBindings (
EObjectType cdkType,
void *object);
    bool isCDKObjectBind (
EObjectType cdkType,
void *object,
chtype key);
    void unbindCDKObject (
EObjectType cdkType,
void *object,
chtype key);
    int getcCDKObject (
CDKOBJS *object);
    int getchCDKObject (
CDKOBJS *object,
boolean *functionKey);

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.

bindCDKObject

creates a key binding between a specific Cdk widget (object) given key (key). The parameter cdkType is of type EObjectType which is one of the following values.

EObjectType_ValueCorresponding_WidgetWidget_Manual_Page
vALPHALISTAlphalist Widgetcdk_alphalist (3)
vBUTTONButton Widgetcdk_button (3)
vBUTTONBOXButtonbox Widgetcdk_buttonbox (3)
vCALENDARCalendar Widgetcdk_calendar (3)
vDIALOGDialog Widgetcdk_dialog (3)
vDSCALEDoubleFloat Widgetcdk_dscale (3)
vENTRYEntry Widgetcdk_entry (3)
vFSCALEFloating Scale Widgetcdk_fscale (3)
vFSELECTFile Selector Widgetcdk_fselect (3)
vFSLIDERFloating Slider Widgetcdk_fslider (3)
vGRAPHGraph Widgetcdk_graph (3)
vHISTOGRAMHistogram Widgetcdk_histogram (3)
vITEMLISTItem List Widgetcdk_itemlist (3)
vLABELLabel Widgetcdk_label (3)
vMARQUEEMarquee Widgetcdk_marquee (3)
vMATRIXMatrix Widgetcdk_matrix (3)
vMENTRYMultiple Line Entry Widgetcdk_mentry (3)
vMENUMenu Widgetcdk_menu (3)
vRADIORadio List Widgetcdk_radio (3)
vSCALEInteger Scale Widgetcdk_scale (3)
vSCROLLScrolling List Widgetcdk_scroll (3)
vSELECTIONSelection List Widgetcdk_selection (3)
vSLIDERSlider Widgetcdk_slider (3)
vSWINDOWScrolling Window Widgetcdk_swindow (3)
vTEMPLATETemplate Entry Widgetcdk_template (3)
vUSCALEUnsigned Scale Widgetcdk_uscale (3)
vUSLIDERUnsigned Slider Widgetcdk_uslider (3)
vVIEWERViewer Widgetcdk_viewer (3)

The parameter function is the callback function. The parameter data points to data passed to the callback function. The parameter key is the key hit which triggered this callback.

checkCDKObjectBind

check to see if a binding for the given key exists. If it does, Cdk runs the associated command and returns its value, normally TRUE.  If no binding exists, return FALSE.

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 exitType value: if earlyExit value is set (not equal to vNEVER_ACTIVATED), the widget sets exitType to that value.

cleanCDKObjectBindings

removes all user defined key bindings from the given widget.

isCDKObjectBind

check to see if a binding for the given key exists. If it does return TRUE. If no binding exists, return FALSE.

unbindCDKObject

removes a specific binding to an object. The parameter are the same as for bindCDKObject.

getcCDKObject

reads a keycode from the given widget. This is deprecated: use getchCDKObject.

getchCDKObject

reads a keycode from the given widget, and sets a flag via the functionKey parameter to indicate if the result is a function key. The functionKey parameter may be null; the keycode is returned whether or not the flag can be set.

If the keycode has been bound to the special function getcCDKBind, then it will be translated to the value which was given for the binding data. Otherwise, a few special cases are performed:

KeyResult
CTRL-AKEY_HOME
CTRL-BKEY_LEFT
CTRL-EKEY_END
CTRL-FKEY_RIGHT
CTRL-Ntab
CTRL-PKEY_BTAB
DELKEY_DC
backspaceKEY_BACKSPACE
carriage returnKEY_ENTER
newlineKEY_ENTER

All of the widgets use getchCDKObject internally for consistency.

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 dialogHelpCB.

________________________________________

#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);
}

________________________________________

See Also

cdk(3), cdk_display(3), cdk_screen(3)

Referenced By

cdk(3), cdk_alphalist(3), cdk_button(3), cdk_buttonbox(3), cdk_calendar(3), cdk_dialog(3), cdk_display(3), cdk_dscale(3), cdk_entry(3), cdk_fscale(3), cdk_fselect(3), cdk_fslider(3), cdk_graph(3), cdk_histogram(3), cdk_itemlist(3), cdk_label(3), cdk_marquee(3), cdk_matrix(3), cdk_mentry(3), cdk_menu(3), cdk_misc(3), cdk_objs(3), cdk_position(3), cdk_process(3), cdk_radio(3), cdk_scale(3), cdk_screen(3), cdk_scroll(3), cdk_selection(3), cdk_slider(3), cdk_swindow(3), cdk_template(3), cdk_traverse(3), cdk_uscale(3), cdk_uslider(3), cdk_viewer(3).

The man pages bindCDKObject(3), checkCDKObjectBind(3), cleanCDKObjectBindings(3), getcCDKObject(3), getchCDKObject(3) and unbindCDKObject(3) are aliases of cdk_binding(3).