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

FreeBSD Manual Pages

  
 
  

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

NAME
       cdk_matrix - curses matrix widget.

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

       #include	<cdk.h>

       int activateCDKMatrix (
		      CDKMATRIX	*matrix,
		      chtype * actions);

       void cleanCDKMatrix (
		      CDKMATRIX	*matrix);

       void cleanCDKMatrixCell (
		      CDKMATRIX	*matrix,
		      int row,
		      int col);

       void destroyCDKMatrix (
		      CDKMATRIX	*matrix);

       void drawCDKMatrix (
		      CDKMATRIX	*matrix,
		      boolean box);

       void eraseCDKMatrix (
		      CDKMATRIX	*matrix);

       boolean getCDKMatrixBox (
		      CDKMENTRY	*matrix);

       char * getCDKMatrixCell (
		      CDKMATRIX	*matrix,
		      int row,
		      int col);

       int getCDKMatrixCol (
		      CDKMENTRY	*matrix);

       int getCDKMatrixRow (
		      CDKMENTRY	*matrix);

       int injectCDKMatrix (
		      CDKMATRIX	*matrix,
		      chtype input);

       int jumpToCell (
		      CDKMATRIX	*matrix,
		      int row,
		      int col);

       void moveCDKMatrix (
		      CDKMATRIX	*matrix,
		      int xpos,
		      int ypos,
		      boolean relative,
		      boolean refresh);

       int moveToCDKMatrixCell (
		      CDKMATRIX	*matrix,
		      int row,
		      int col);

       CDKMATRIX *newCDKMatrix (
		      CDKSCREEN	*cdkscreen,
		      int xpos,
		      int ypos,
		      int screenRows,
		      int screenCols,
		      int actualRows,
		      int actualCols,
		      const char *title,
		      CDK_CONST	char **rowTitles,
		      CDK_CONST	char **colTitles,
		      int *columnWidths,
		      int *columnTypes,
		      int rowSpace,
		      int colSpace,
		      chtype filler,
		      int dominantAttribute,
		      boolean boxMatrix,
		      boolean boxCell,
		      boolean shadow);

       void positionCDKMatrix (
		      CDKMATRIX	*matrix);

       void setCDKMatrix (
		      CDKMATRIX	*matrix,
		      char *info[MAX_MATRIX_ROWS][MAX_MATRIX_COLS],
		      int rows,
		      int *columnLengths);

       void setCDKMatrixBackgroundAttrib (
		      CDKMATRIX	*matrix,
		      chtype attribute);

       void setCDKMatrixBackgroundColor	(
		      CDKMATRIX	*matrix,
		      const char * color);

       void setCDKMatrixBox (
		      CDKMENTRY	*matrix,
		      boolean boxWidget);

       void setCDKMatrixBoxAttribute (
		      CDKMATRIX	*matrix,
		      chtype character);

       void setCDKMatrixCB (
		      CDKMATRIX	*matrix,
		      MATRIXCB callbackFunction);

       int setCDKMatrixCell (
		      CDKMATRIX	*matrix,
		      int row,
		      int col,
		      const char *value);

       void setCDKMatrixCells (
		      CDKMATRIX	*matrix,
		      CDK_CONST	char **info,
		      int rows,
		      int cols,
		      int *columnLengths);

       void setCDKMatrixHorizontalChar (
		      CDKMATRIX	*matrix,
		      chtype character);

       void setCDKMatrixLLChar (
		      CDKMATRIX	*matrix,
		      chtype character);

       void setCDKMatrixLRChar (
		      CDKMATRIX	*matrix,
		      chtype character);

       void setCDKMatrixPostProcess (
		      CDKMATRIX	*matrix,
		      PROCESSFN	callback,
		      void * data);

       void setCDKMatrixPreProcess (
		      CDKMATRIX	*matrix,
		      PROCESSFN	callback,
		      void * data);

       void setCDKMatrixULChar (
		      CDKMATRIX	*matrix,
		      chtype character);

       void setCDKMatrixURChar (
		      CDKMATRIX	*matrix,
		      chtype character);

       void setCDKMatrixVerticalChar (
		      CDKMATRIX	*matrix,
		      chtype character);

DESCRIPTION
       The Cdk matrix widget creates a matrix widget.  The following are func-
       tions which create or manipulate	the Cdk	matrix box widget.

AVAILABLE FUNCTIONS
       activateCDKMatrix
	    activates the matrix widget	and lets the user  interact  with  the
	    widget.

	    o	The parameter matrix is	a pointer to a non-NULL	matrix 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 then this
		function will return 1.	 It will  also	set  the  widget  data
		exitType to vNORMAL.

		If  the	character entered into this widget was ESCAPE then the
		widget will return a value of -1 and the widget	data  exitType
		will be	set to vESCAPE_HIT.

	    o	The  matrix  cell  contents can	be retrieved by	using the info
		array of the matrix widget.

       cleanCDKMatrix
	    clears the information from	all cells of the matrix.

       cleanCDKMatrixCell
	    clears the information from	the specified cell of the matrix.

       destroyCDKMatrix
	    removes the	widget from the	screen and  frees  memory  the	object
	    used.

       drawCDKMatrix
	    draws  the	matrix	widget on the screen.  If the box parameter is
	    true, the widget is	drawn with a box.

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

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

       getCDKMatrixCell
	    returns the	contents of the	cell located by	the row	and col	pair.

       getCDKMatrixCol
	    returns the	current	column index.

       getCDKMatrixRow
	    returns the	current	row index.

       injectCDKMatrix
	    injects a single character into the	widget.

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

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

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

		RETURN or TAB
		       the  function  returns  1.  The widget data exitType is
		       set to vNORMAL.

		ESCAPE the function returns -1.	 The widget data  exitType  is
		       set to vESCAPE_HIT.

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

	    o	The  matrix  cell  contents can	be retrieved by	using the info
		array of the matrix widget.

       jumpToCell
	    provides an	interactive method of moving to	a cell.	 It pops up  a
	    scale widget and asks which	cell the user wants to go to.  Then it
	    performs the jump.

       moveCDKMatrix
	    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 may be an integer or	one of the pre-defined
		values 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	get refreshed after the	move.

       moveToCDKMatrixCell
	    jumps to the given cells dictated by the parameters	row  and  col.
	    It returns a value of TRUE or FALSE	depending if the move was suc-
	    cessful.

       newCDKMatrix
	    creates a matrix widget and	returns	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.

	    screenRows and

	    screenCols
		 are the number	of rows	and columns to	be  displayed  on  the
		 screen	respectively.

	    actualRows and

	    actualCols
		 are the number	of actual rows and columns the matrix has.

	    title
		 is  the string	which will be displayed	at the top of the wid-
		 get.  The title can be	more than one  line;  just  provide  a
		 carriage return character at the line break.

	    rowTitles and

	    colTitles
		 are the titles	along the row and columns respectively.

	    columnWidths
		 is  an	array of integers stating how wide the individual col-
		 umns are to be.

	    columnTypes
		 is an array of	integers which correspond  to  the  individual
		 column	 display types.	 The values of the array should	be as-
		 signed	a value	of type	EDisplayType.  See cdk_display (3) for
		 legal values of EDisplayType.

	    rowSpace and

	    colSpace
		 dictate  how  much white space	is to be between rows and col-
		 umns respectively.

	    filler
		 is the	character to use in empty space	within a cell.

	    dominantAttribute
		 states	which (the rows	or the columns)	will have the dominant
		 character  attributes.	 This is stated	when a cell has	both a
		 row attribute and a column attribute.

		 If the	value of the parameter dominantAttribute is set	to ROW
		 then  the  attribute  of the row will be displayed.  If it is
		 set to	COL then the column's attributes will be displayed in-
		 stead.

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

	    boxCell
		 is  true  if  the  individual	cells  should have boxes drawn
		 around	them.

	    shadow
		 turns the shadow on or	off around this	widget.

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

       positionCDKMatrix
	    allows  the	user to	move the widget	around the screen via the cur-
	    sor/keypad keys.  See cdk_position (3) for key bindings.

       setCDKMatrix
	    lets the programmer	modify certain elements	of an existing	matrix
	    widget.

	    o	The  parameter	info  is an array of char * which contains the
		cell information.

	    o	The parameter rows has the number of rows

	    o	the parameter info contains,

	    o	columnLengths has the lengths of  the  individual  columns  in
		info.

	    Do	not use	this function.	It is obsolete,	provided only for com-
	    patibility with older versions of CDK.  Use	setCDKMatrixCells.

       setCDKMatrixBackgroundAttrib
	    sets the background	attribute of the widget.  The parameter	attri-
	    bute is a curses attribute,	e.g., A_BOLD.

       setCDKMatrixBackgroundColor
	    sets  the  background color	of the widget.	The parameter color is
	    in the format of the Cdk format strings.  See cdk_display (3).

       setCDKMatrixBox
	    sets whether the widget will be drawn with a box around it.

       setCDKMatrixBoxAttribute
	    sets the attribute of the box.

       setCDKMatrixCB
	    allows the programmer to set a  different  widget  input  handler.
	    The	 parameter  callbackFunction is	of type	MATRIXCB.  The default
	    function is	CDKMatrixCallBack.

       setCDKMatrixCell
	    sets the contents of the cell located by the  row  and  col	 pair.
	    The	value of the cell will be set to value.

       setCDKMatrixCells,
	    lets the programmer	initialize elements of an existing matrix wid-
	    get.

       o   The parameter info is an array of char * which  contains  the  cell
	   information.

	   o   The parameter rows has the number of rows

	   o   The parameter cols has the number of columns

	   o   The  parameter  info  contains,	while  columnLengths  has  the
	       lengths of the individual columns in info.

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

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

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

       setCDKMatrixPostProcess
	    allows  the	 user to have the widget call a	function after the key
	    has	been applied to	the widget.

	    o	The parameter function is the callback function.

	    o	The parameter data points to data passed to the	callback func-
		tion.

	    To learn more about	post-processing	see cdk_process	(3).

       setCDKMatrixPreProcess
	    allows  the	user to	have the widget	call a function	after a	key is
	    hit	and before the key is applied to the widget.

	    o	The parameter function is the callback function.

	    o	The parameter data points to data passed to the	callback func-
		tion.

	    To learn more about	pre-processing see cdk_process (3).

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

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

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

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					|
	    +-----------------------------------------------------------+
	    |Left Arrow	       Moves one cell to the left.		|
	    |Right Arrow       Moves the cell to the right.		|
	    |Tab	       Moves the cell to the right.		|
	    |Up	Arrow	       Moves one cell up.			|
	    |Down Arrow	       Moves one cell down.			|
	    |Next Page	       Moves one page forward.			|
	    |Ctrl-F	       Moves one page forward.			|
	    |Prev Page	       Moves one page backward.			|
	    |Ctrl-B	       Moves one page backward.			|
	    |Ctrl-G	       Calls  the  function  jumpToCell	and re-	|
	    |		       quests which cell  the  user  wishes  to	|
	    |		       jump to.					|
	    |Ctrl-P	       Pastes  whatever	is in the paste	buffer,	|
	    |		       into the	current	cell.			|
	    |Ctrl-K	       Cuts the	contents from the current  cell	|
	    |		       and saves a copy	in the paste buffer.	|
	    |Ctrl-T	       Copies  the contents of the current cell	|
	    |		       into the	paste buffer.			|
	    |Ctrl-E	       Erases the contents of the current cell.	|
	    |Delete	       Deletes the character before the	cursor,	|
	    |		       moves cursor left.  There is no function	|
	    |		       to delete the character	at  the	 cursor	|
	    |		       since  there are	no functions for moving	|
	    |		       the cursor within the edited text.	|
	    |Backspace	       Deletes	the  character	before	cursor,	|
	    |		       moves cursor left.			|
	    |Ctrl-H	       Deletes the character before the	cursor.	|
	    |Return	       Exits  the  widget  and returns 1.  This	|
	    |		       also sets the widget  data  exitType  to	|
	    |		       vNORMAL.					|
	    |Escape	       Exits  the  widget and returns -1.  This	|
	    |		       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_position(3),	cdk_screen(3)

								 cdk_matrix(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=activateCDKMatrix&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help