Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
cdk_template(3)		   Library Functions Manual	       cdk_template(3)

NAME
       cdk_template - a	curses template	widget.

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

       #include	<cdk.h>

       char *activateCDKTemplate (
		      CDKTEMPLATE *template,
		      chtype * actions);

       void cleanCDKTemplate (
		      CDKTEMPLATE *template);

       void destroyCDKTemplate (
		      CDKTEMPLATE *template);

       void drawCDKTemplate (
		      CDKTEMPLATE *template,
		      boolean box);

       void eraseCDKTemplate (
		      CDKTEMPLATE *template);

       boolean getCDKTemplateBox (
		      CDKTEMPLATE *template);

       int getCDKTemplateMin (
		      CDKTEMPLATE *template);

       char *getCDKTemplateValue (
		      CDKTEMPLATE *template);

       char *injectCDKTemplate (
		      CDKTEMPLATE *template,
		      chtype input);

       char *mixCDKTemplate (
		      CDKTEMPLATE *template);

       void moveCDKTemplate (
		      CDKTEMPLATE *template,
		      int xpos,
		      int ypos,
		      boolean relative,
		      boolean refresh);

       CDKTEMPLATE *newCDKTemplate (
		      CDKSCREEN	*cdkscreen,
		      int xpos,
		      int ypos,
		      const char *title,
		      const char *label,
		      const char *plate,
		      const char *overlay,
		      boolean box,
		      boolean shadow);

       void positionCDKTemplate	(
		      CDKTEMPLATE *template);

       void setCDKTemplate (
		      CDKTEMPLATE *template,
		      const char *value,
		      boolean box);

       void setCDKTemplateBackgroundAttrib (
		      CDKTEMPLATE *template,
		      chtype attribute);

       void setCDKTemplateBackgroundColor (
		      CDKTEMPLATE *template,
		      const char * color);

       void setCDKTemplateBox (
		      CDKTEMPLATE *template,
		      boolean box);

       void setCDKTemplateBoxAttribute (
		      CDKTEMPLATE *template,
		      chtype character);

       void setCDKTemplateCB (
		      CDKTEMPLATE *template,
		      TEMPLATECB callbackFunction);

       void setCDKTemplateHorizontalChar (
		      CDKTEMPLATE *template,
		      chtype character);

       void setCDKTemplateLLChar (
		      CDKTEMPLATE *template,
		      chtype character);

       void setCDKTemplateLRChar (
		      CDKTEMPLATE *template,
		      chtype character);

       void setCDKTemplateMin (
		      CDKTEMPLATE *template,
		      int minimum);

       void setCDKTemplatePostProcess (
		      CDKTEMPLATE *template,
		      PROCESSFN	callback,
		      void * data);

       void setCDKTemplatePreProcess (
		      CDKTEMPLATE *template,
		      PROCESSFN	callback,
		      void * data);

       void setCDKTemplateULChar (
		      CDKTEMPLATE *template,
		      chtype character);

       void setCDKTemplateURChar (
		      CDKTEMPLATE *template,
		      chtype character);

       void setCDKTemplateValue	(
		      CDKTEMPLATE *template,
		      const char *value);

       void setCDKTemplateVerticalChar (
		      CDKTEMPLATE *template,
		      chtype character);

       char *unmixCDKTemplate (
		      CDKTEMPLATE *template,
		      const char *string);

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.

AVAILABLE FUNCTIONS
       activateCDKTemplate
	    activates  the template widget and lets the	user interact with the
	    widget.

	    o	The parameter template is a pointer  to	 a  non-NULL  template
		widget.

	    o	If  the	actions	parameter is passed with a non-NULL value, the
		characters in the array	will be	injected into the widget.

		To activate the	widget interactively pass in  a	 NULL  pointer
		for actions.

	    If	the  character	entered	into this widget is RETURN or TAB then
	    this function will return a	char *	representing  the  information
	    typed  into	the widget and the widget data exitType	will be	set to
	    vNORMAL.

	    If the character entered was ESCAPE	then the function will	return
	    NULL pointer and the widget	data exitType is set to	vESCAPE_HIT.

       cleanCDKTemplate
	    clears the information from	the field.

       destroyCDKTemplate
	    removes the	widget from the	screen and frees any memory the	object
	    used.

       drawCDKTemplate
	    draws the template widget on the screen.  If box is	true, the wid-
	    get	is drawn with a	box.

       eraseCDKTemplate
	    removes  the  widget  from	the screen.  This does NOT destroy the
	    widget.

       getCDKTemplateBox
	    returns true if the	widget will be drawn with a box	around it.

       getCDKTemplateMin
	    returns the	minimum	characters that	must  be  entered  before  the
	    widget will	exit.

       getCDKTemplateValue
	    returns the	current	value of the widget.

       injectCDKTemplate
	    injects a single character into the	widget.

	    o	The  parameter	template  is  a	pointer	to a non-NULL template
		widget.

	    o	The parameter character	is the character to  inject  into  the
		widget.

	    The	 return	 value	and side-effect	(setting the widget data exit-
	    Type) depend upon the injected character:

	    RETURN or TAB
		   the function	returns	a char * representing the  information
		   typed  into the widget.  The	widget data exitType is	set to
		   vNORMAL.

	    ESCAPE the function	returns	a NULL pointer.	 The widget data exit-
		   Type	is set to vESCAPE_HIT.

	    Otherwise
		   unless  modified  by	 preprocessing,	 postprocessing	or key
		   bindings, the function returns a NULL pointer.  The	widget
		   data	exitType is set	to vEARLY_EXIT.

       mixCDKTemplate
	    returns a char* pointer to the field value and the plate.

       moveCDKTemplate
	    moves the given widget to the given	position.

	    o	The  parameters	xpos and ypos are the new position of the wid-
		get.

		The parameter xpos is an integer or one	of the predefined val-
		ues TOP, BOTTOM, and CENTER.

		The parameter ypos may be an integer or	one of the pre-defined
		values LEFT, RIGHT, and	CENTER.

	    o	The parameter relative states whether the xpos/ypos pair is  a
		relative move or an absolute move.

		For  example,  if  xpos	 = 1 and ypos =	2 and relative = TRUE,
		then the widget	would move one row down	and two	columns	right.
		If  the	value of relative was FALSE then the widget would move
		to the position	(1,2).

		Do not use the values TOP, BOTTOM, LEFT, RIGHT,	or CENTER when
		relative = TRUE	(weird things may happen).

	    o	The  final  parameter  refresh is a boolean value which	states
		whether	the widget will	be repainted after the move.

       newCDKTemplate
	    creates a template widget, returning a pointer to it.  Parameters:

	    screen
		 is the	screen you wish	this widget to be placed in.

	    xpos controls the placement	of the	object	along  the  horizontal
		 axis.	 It may	be an integer or one of	the pre-defined	values
		 LEFT, RIGHT, and CENTER.

	    ypos controls the placement	of the object along the	vertical axis.
		 It  may  be  an integer or one	of the pre-defined values TOP,
		 BOTTOM, and CENTER.

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

	    label
		 is the	string to display in the label of the template field.

	    plate
		 defines the character to allow	at each	position in  the  tem-
		 plate	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 wid-
		 get.  The following table lists the format types.

		  Plate_Character   Effect
		  ------------------------------------------------------
		  #		    Accepts an integer.
		  A		    Accepts an alphabetic value.
		  C		    Accepts an alphabetic value.  Auto-
				    matically converts the character to
				    upper case.
		  c		    Accepts an alphabetic value.  Auto-
				    matically converts the character to
				    lower case.
		  M		    Accepts alphanumeric characters.
		  X		    Accepts  alphanumeric   characters.
				    Automatically  converts the	charac-
				    ter	to upper case.
		  x		    Accepts  alphanumeric   characters.
				    Automatically  converts the	charac-
				    ter	to upper case.
		  Anything else	    Ignored and	assumed	a  non-editable
				    position.
		  ------------------------------------------------------

	    overlay
		 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 dis-
		 play YY/MM/DD on an empty template field.

	    box	 is true if the	widget should be drawn with a box around it.

	    shadow
		 turns the shadow on or	off around this	widget.

	    If the widget could	not be created then  a	NULL  pointer  is  re-
	    turned.

       positionCDKTemplate
	    allows  the	user to	move the widget	around the screen via the sin-
	    gle	keystroke commands.  See cdk_position (3) for key bindings.

       setCDKTemplate
	    lets the programmer	modify certain elements	of  an	existing  tem-
	    plate widget.

	    The	 parameter names correspond to the same	parameter names	listed
	    in the newCDKTemplate function.

       setCDKTemplateBackgroundAttrib
	    sets the background	attribute of the widget.

	    The	parameter attribute is a curses	attribute, e.g., A_BOLD.

       setCDKTemplateBackgroundColor
	    sets the background	color of the widget.

	    The	parameter color	is in the format of the	Cdk format strings.

	    For	more information, see the cdk_display (3).

       setCDKTemplateBox
	    sets a flag, true if the widget will be drawn with	a  box	around
	    it.

       setCDKTemplateBoxAttribute
	    sets the attribute of the box.

       setCDKTemplateCB
	    allows the programmer to set a different widget input handler.

	    The	parameter callbackFunction is of type TEMPLATECB.

	    The	default	input handler is CDKTemplateCallBack.

       setCDKTemplateHorizontalChar
	    sets  the  horizontal  drawing  character for the box to the given
	    character.

       setCDKTemplateLLChar
	    sets the lower left	hand corner of the widget's box	to  the	 given
	    character.

       setCDKTemplateLRChar
	    sets  the lower right hand corner of the widget's box to the given
	    character.

       setCDKTemplateMin
	    sets the minimum number of characters that must be entered	before
	    the	widget will exit.

       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-process-
	    ing	see cdk_process	(3).

       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 cdk_process	(3).

       setCDKTemplateULChar
	    sets  the  upper left hand corner of the widget's box to the given
	    character.

       setCDKTemplateURChar
	    sets the upper right hand corner of	the widget's box to the	 given
	    character.

       setCDKTemplateValue
	    sets a value in the	widget.

       setCDKTemplateVerticalChar
	    sets the vertical drawing character	for the	box to the given char-
	    acter.

       unmixCDKTemplate
	    returns a char* pointer to the field value without any plate char-
	    acters.

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 wid-
       get.

	       +----------------+-------------------------------------+
	       |Key		| Action			      |
	       +----------------+-------------------------------------+
	       +----------------+-------------------------------------+
	       |Delete		| Deletes the character	at  the	 cur- |
	       |		| sor.				      |
	       +----------------+-------------------------------------+
	       |Backspace	| Deletes  the	character before cur- |
	       |		| sor, moves cursor left.	      |
	       +----------------+-------------------------------------+
	       |Ctrl-P		| Pastes whatever  is  in  the	paste |
	       |		| buffer, into the widget.	      |
	       +----------------+-------------------------------------+
	       |Ctrl-K		| Cuts	the  contents from the widget |
	       |		| and saves a copy in the paste	 buf- |
	       |		| fer.				      |
	       +----------------+-------------------------------------+
	       |Ctrl-T		| Copies  the  contents	of the widget |
	       |		| into the paste buffer.	      |
	       +----------------+-------------------------------------+
	       |Ctrl-E		| Erases the contents of the widget.  |
	       +----------------+-------------------------------------+
	       |Return		| Exits	 the  widget  and  returns  a |
	       |		| char*	 representing the information |
	       |		| which	was typed into the field.  It |
	       |		| also	sets the widget	data exitType |
	       |		| to vNORMAL.			      |
	       +----------------+-------------------------------------+
	       |Tab		| Exits	 the  widget  and  returns  a |
	       |		| char*	 representing the information |
	       |		| which	was typed into the field.  It |
	       |		| also	sets the widget	data exitType |
	       |		| to vNORMAL.			      |
	       +----------------+-------------------------------------+
	       |Escape		| Exits	the widget and returns a NULL |
	       |		| pointer.   It	 also sets the widget |
	       |		| data exitType	to vESCAPE_HIT.	      |
	       +----------------+-------------------------------------+
	       |Ctrl-L		| Refreshes the	screen.		      |
	       +----------------+-------------------------------------+
SEE ALSO
       cdk(3), cdk_binding(3), cdk_display(3), cdk_screen(3)

							       cdk_template(3)

NAME | SYNOPSIS | DESCRIPTION | AVAILABLE FUNCTIONS | KEY BINDINGS | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=activateCDKTemplate&sektion=3&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help