cdk_template(3)

📦
version 5.0.20260119 · 4 versions
, in debian trixie, fedora 43, fedora 44, nixos 26.05, nixpkgs unstable, ubuntu questing, ubuntu resolute, ubuntu stonking

🌈 cdk_template — the Cdk template widget, bestie edition 🌈

okay so you're here for cdk_template(3) — it's a C library call, part of Cdk, and it is literally the template widget. Cursor-ready, entry-field energy, but with a pre-set format. We're doing this in parts btw, so buckle up, we're only at the beginning. 💖

✨ NAME ✨

cdk_template — the Cdk template widget. that's the whole name section. short, sweet, iconic. 🎀

🦋 SYNOPSIS 🦋

first you gotta compile it in, like so:

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

and obviously you bring the header:

#include <cdk.h>

then, the entire squad of functions, exactly as they are, no edits, no cap:

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

like… that's a LOT of functions and every single one of them is here, we don't skip, we don't gatekeep. 💅

💜 DESCRIPTION 💜

so the Cdk template widget does one thing and it does it beautifully: it makes a template widget, and that widget lets a user type information into an entry field that already has a pre-set field format. pre-set field format — that's the whole vibe. the shape of the input is decided ahead of time and the user just fills it in.

typical uses? a date field or a time field. yeah. those. the classic "please type it in this exact shape" situations. 🕐📅

and the functions listed in the synopsis up there? those are the functions which create or manipulate the Cdk template box widget. creation, manipulation, all of it. they're your besties for this widget. 🫶

heads up bestie — this page keeps going. more parts incoming, so don't wander off. 🌸

✨ AVAILABLE FUNCTIONS ✨

okay bestie, this is the whole squad of functions you can call on your template widget. no cap, every single one is here. let's go 💅

activateCDKTemplate

activates the template widget and lets the user interact with the widget.

  • The parameter template is a pointer to a non-NULL template widget.
  • 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. periodt. ✨

destroyCDKTemplate

removes the widget from the screen and frees any memory the object used. it's giving cleanup energy 🧹

drawCDKTemplate

draws the template widget on the screen. If box is true, the widget is drawn with a box.

eraseCDKTemplate

removes the widget from the screen. This does NOT destroy the widget. like, it's still there, just invisible. lowkey spooky 👻

getCDKTemplateBox

returns true if the widget will be drawn with a box around it. simple as that 💅

getCDKTemplateMin

returns the minimum characters that must be entered before the widget will exit. no rushing, bestie 🛑

getCDKTemplateValue

returns the current value of the widget. it's giving "what's in the box" 📦

injectCDKTemplate

injects a single character into the widget.

  • The parameter template is a pointer to a non-NULL template widget.
  • 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 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 exitType 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. mixing it up fr fr 🎨

moveCDKTemplate

moves the given widget to the given position.

  • The parameters xpos and ypos are the new position of the widget. The parameter xpos is an integer or one of the predefined values TOP, BOTTOM, and CENTER. The parameter ypos may be an integer or one of the pre-defined values LEFT, RIGHT, and CENTER.
  • 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). ⚠️
  • 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 template 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 widget. The following table lists the format types.

Plate_Character → Effect:

  • # — Accepts an integer.
  • A — Accepts an alphabetic value.
  • C — Accepts an alphabetic value. Automatically converts the character to upper case.
  • c — Accepts an alphabetic value. Automatically converts the character to lower case.
  • M — Accepts alphanumeric characters.
  • X — Accepts alphanumeric characters. Automatically converts the character to upper case.
  • x — Accepts alphanumeric characters. Automatically converts the character 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 display 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 returned.

positionCDKTemplate

allows the user to move the widget around the screen via the single keystroke commands. See cdk_position (3) for key bindings. it's giving drag-and-drop but with keys 🕹️

setCDKTemplate

lets the programmer modify certain elements of an existing template widget. The parameter names correspond to the same parameter names listed in the newCDKTemplate function. glow-up time ✨

setCDKTemplateBackgroundAttrib

sets the background attribute of the widget. The parameter attribute is a curses attribute, e.g., A_BOLD. bold background? yes please 💪

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). color theory but make it curses 🌈

setCDKTemplateBox

sets a flag, true if the widget will be drawn with a box around it. boxed like a lunchable 🍱

setCDKTemplateBoxAttribute

sets the attribute of the box. fancy box energy 💅

setCDKTemplateCB

allows the programmer to set a different widget input handler. The parameter callbackFunction is of type TEMPLATECB. The default input handler is CDKTemplateCallBack. custom vibes only 😎

setCDKTemplateHorizontalChar

sets the horizontal drawing character for the box to the given character. horizontal lines but make it personal ➖

setCDKTemplateLLChar

sets the lower left hand corner of the widget's box to the given character. corner customization, we love to see it 📐

setCDKTemplateLRChar

sets the lower right hand corner of the widget's box to the given character. another corner, another slay 🎀

setCDKTemplateMin

sets the minimum number of characters that must be entered before the widget will exit. setting the bar high, bestie 📈

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-processing see cdk_process (3). after-party function 🎉

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). pre-game function 🏁

setCDKTemplateULChar

sets the upper left hand corner of the widget's box to the given character. top left corner representation 🌟

setCDKTemplateURChar

sets the upper right hand corner of the widget's box to the given character. top right corner, we see you 👀

setCDKTemplateValue

sets a value in the widget. putting a value on it, periodt 💖

setCDKTemplateVerticalChar

sets the vertical drawing character for the box to the given character. vertical lines, standing tall 🦋

unmixCDKTemplate

returns a char* pointer to the field value without any plate characters. unmixed, unbothered, in my lane ✨

⌨️ KEY BINDINGS ⌨️

okay so once you actually activate the widget (like, it's live, it's on screen, it's the main character), there are a bunch of default key bindings that are there to help you type stuff in and mess with it fast. the original page lays these out in a table, and we're doing the exact same info, just with ✨flavor✨. here's every key and what it does, no cap:

  • Delete — deletes the character sitting right at the cursor. bye bestie 💅
  • Backspace — deletes the character before the cursor, and then the cursor scoots left. it's giving "undo but make it one char at a time".
  • Ctrl-P — pastes whatever is chillin' in the paste buffer, straight into the widget. 🫶
  • Ctrl-K — cuts the contents out of the widget and saves a copy in the paste buffer. it's gone but not forgotten.
  • Ctrl-T — copies the contents of the widget into the paste buffer. nothing leaves, everything gets duplicated. iconic.
  • Ctrl-E — erases the contents of the widget. full reset, no crumbs. 😭
  • Return — exits the widget and returns a char* representing the information that was typed into the field. it also sets the widget data exitType to vNORMAL. so like, a clean exit, a normal one, the standard vibe.
  • Tab — exits the widget and returns a char* representing the information that was typed into the field. it also sets the widget data exitType to vNORMAL. yep, literally the same deal as Return, vNORMAL and all. slay.
  • Escape — exits the widget and returns a NULL pointer. it also sets the widget data exitType to vESCAPE_HIT. so you bailed, and the code knows you bailed. ⭐
  • Ctrl-L — refreshes the screen. glow-up for your terminal, periodt.
lowkey fun fact: the original table has a lil empty row right after the Key / Action header row, with no key and no action in it. we don't know her, but we're keeping her in spirit 💀

🔗 SEE ALSO 🔗

go read these next, bestie, they're all family:

and that's the whole page, babes!! 🎀 this was cdk_template(3) from 2025-01-14 — go forth and template your lil heart out, you absolute Unix icon 👑💖

📦 where this page comes from