cdk_histogram(3)

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

💖 cdk_histogram(3) 💖

library calls ✨ bestie, this is the whole vibe of the Cdk histogram widget, and yes we're doing the long version because you deserve the full tea 🫖

🌸 NAME 🌸

cdk_histogram</purlle> — the Cdk histogram widget 💅

✨ SYNOPSIS ✨

okay so first things first, you link against the library like this:

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

and you grab the header, obviously:

#include <cdk.h>

then here's every single function the widget hands you, no cap, all of them, in order:

void activateCDKHistogram (
               CDKHISTOGRAM *histogram,
               chtype unused);

void destroyCDKHistogram (
               CDKHISTOGRAM *histogram);

void drawCDKHistogram (
               CDKHISTOGRAM *histogram,
               boolean box);

void eraseCDKHistogram (
               CDKHISTOGRAM *histogram);

boolean getCDKHistogramBox (
               CDKHISTOGRAM *histogram);

chtype getCDKHistogramFillerChar (
               CDKHISTOGRAM *histogram);

int getCDKHistogramHighValue (
               CDKHISTOGRAM *histogram);

int getCDKHistogramLowValue (
               CDKHISTOGRAM *histogram);

chtype getCDKHistogramStatsAttr (
               CDKHISTOGRAM *histogram);

int getCDKHistogramStatsPos (
               CDKHISTOGRAM *histogram);

int getCDKHistogramValue (
               CDKHISTOGRAM *histogram);

EHistogramDisplayType getCDKHistogramViewType (
               CDKHISTOGRAM *histogram);

void moveCDKHistogram (
               CDKHISTOGRAM *histogram,
               int xpos,
               int ypos,
               boolean relative,
               boolean refresh);

CDKHISTOGRAM *newCDKHistogram (
               CDKSCREEN *cdkscreen,
               int xpos,
               int ypos,
               int height,
               int width,
               int orient,
               const char *title,
               boolean box,
               boolean shadow);

void positionCDKHistogram (
               CDKHISTOGRAM *histogram);

void setCDKHistogram (
               CDKHISTOGRAM *histogram,
               EHistogramDisplayType viewType,
               int statsPos,
               chtype statsAttribute,
               int lowValue,
               int highValue,
               int currentValue,
               chtype fillerCharacter,
               boolean box);

void setCDKHistogramBackgroundAttrib (
               CDKHISTOGRAM *histogram,
               chtype attribute);

void setCDKHistogramBackgroundColor (
               CDKHISTOGRAM *histogram,
               const char * color);

void setCDKHistogramBox (
               CDKHISTOGRAM *histogram,
               boolean box);

void setCDKHistogramBoxAttribute (
               CDKHISTOGRAM *histogram,
               chtype character);

void setCDKHistogramDisplayType (
               CDKHISTOGRAM *histogram,
               EHistogramDisplayType viewtype);

void setCDKHistogramFillerChar (
               CDKHISTOGRAM *histogram,
               chtype fillerCharacter);

void setCDKHistogramHorizontalChar (
               CDKHISTOGRAM *histogram,
               chtype character);

void setCDKHistogramLLChar (
               CDKHISTOGRAM *histogram,
               chtype character);

void setCDKHistogramLRChar (
               CDKHISTOGRAM *histogram,
               chtype character);

void setCDKHistogramStatsAttr (
               CDKHISTOGRAM *histogram,
               chtype statsAttribute);

void setCDKHistogramStatsPos (
               CDKHISTOGRAM *histogram,
               int statsPosition);

void setCDKHistogramULChar (
               CDKHISTOGRAM *histogram,
               chtype character);

void setCDKHistogramURChar (
               CDKHISTOGRAM *histogram,
               chtype character);

void setCDKHistogramValue (
               CDKHISTOGRAM *histogram,
               int lowValue,
               int highValue,
               int currentValue);

void setCDKHistogramVerticalChar (
               CDKHISTOGRAM *histogram,
               chtype character);

void setCDKHistogramViewType (
               CDKHISTOGRAM *histogram,
               EHistogramDisplayType viewType);

like, look at that list. it's giving organized. 🎀

🦋 DESCRIPTION 🦋

so the Cdk histogram widget does exactly what it says on the tin — it creates a histogram widget. groundbreaking, i know, but stay with me 💀

this widget can draw a vertical histogram or a horizontal histogram, your call, no wrong answers. pick whichever one fits the aesthetic of your terminal bestie 🌈

and all those functions up in the synopsis? they create or manipulate the Cdk histogram box widget. that's the whole job. that's the assignment. and it ate, honestly 👑

heads up — this is only part 1, so hold that thought, there's more coming and you're gonna wanna keep reading 🫶

✨ AVAILABLE FUNCTIONS ✨

okay bestie, this is the part where we meet the whole squad 💖 every single function, no skips, no cuts. let's go.

  • activateCDKHistogram — obsolete entrypoint, and when I say obsolete I mean it 💀 it literally just calls drawCDKHistogram. that's it. that's the whole function.
  • destroyCDKHistogram — takes the widget off your screen AND frees up the memory it was using. full cleanup, no crumbs left behind 🧹
  • drawCDKHistogram — draws the histogram widget on the screen. if the box parameter is true, it gets drawn with a box around it 🎁
  • eraseCDKHistogram — removes the widget from the screen. but NOT destroy it!! like, it's gone from view but it very much still exists, okay? do not confuse these two 😭
  • getCDKHistogramBox — returns true if the widget is gonna be drawn with a box around it.
  • getCDKHistogramFillerChar — hands you back the character being used to draw the histogram bar.
  • getCDKHistogramHighValue — returns the high value of the histogram.
  • getCDKHistogramLowValue — returns the low value of the histogram.
  • getCDKHistogramStatsAttr — returns the attribute of the statistics of the histogram.
  • getCDKHistogramStatsPos — tells you where the histogram is gonna draw the statistics.
  • getCDKHistogramValue — returns the current value of the histogram.
  • getCDKHistogramViewType — returns the view type of the histogram widget.

💫 moveCDKHistogram

moves the given widget to the given position. iconic behavior honestly.

  • the parameters xpos and ypos are the new position of the widget.
  • the parameter xpos may be an integer or one of the pre-defined values TOP, BOTTOM, and CENTER.
  • the parameter ypos can 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). bestie I am begging you 🙏
  • the final parameter refresh is a boolean value which states whether the widget will get refreshed after the move.

🌈 newCDKHistogram

creates a histogram widget and returns a pointer to it. brand new widget, fresh out the box 🎀

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 which will be displayed at the top of the widget. the title can be more than one line; just provide a carriage return character at the line break. multi-line title? she contains multitudes 💅
  • height and
  • width — control the height and width of the widget. if you provide a value of zero for either of the height or the width, the widget will be created with the full width and height of the screen. if you provide a negative value, the widget will be created the full height or width minus the value provided.
  • orient — specifies the orientation of the histogram. it is one of these pre-defined values: VERTICAL and HORIZONTAL.
  • label — is the string to use as the label of the histogram.
  • 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. no widget, no vibe 😭

🦋 positionCDKHistogram

allows the user to move the widget around the screen via the cursor/keypad keys. see cdk_position (3) for key bindings. drag her around like a little sticker, she doesn't mind 💜

👑 setCDKHistogram

lets the programmer set the specific values of the histogram widget. this is the main character of the whole page tbh.

  • the parameter viewType specifies the type of histogram to draw. the following table lists the valid values and the results.
    • vNONE — displays no information about the current values.
    • vPERCENT — displays the current value as a percentage.
    • vFRACTION — displays the current value as a fraction.
    • vREAL — displays the current value.
  • the statsPosition parameter states where the statistics will be displayed. it accepts TOP, BOTTOM, and CENTER.
  • the parameter statsAttribute sets the attributes of the statistics.
  • the parameters lowValue, highValue, and currentValue are the low, high, and current values respectively.
  • the filler character is the character to use in the unused space in the histogram.
  • if the box parameter is true, the widget is drawn with a box.

💖 the setters, aka the glow-up crew

  • setCDKHistogramBackgroundAttrib — sets the background color attribute of the widget. the parameter attribute is a curses attribute, e.g., A_BOLD.
  • setCDKHistogramBackgroundColor — sets the background color of the widget. the parameter color is in the format of the Cdk format strings. see cdk_display (3).
  • setCDKHistogramBox — sets whether the widget will be drawn with a box around it.
  • setCDKHistogramBoxAttribute — sets the attribute of the box.
  • setCDKHistogramDisplayType — sets the display type (see getCDKHistogramViewType).
  • setCDKHistogramFillerChar — sets the character to use when drawing the histogram bar.
  • setCDKHistogramHorizontalChar — sets the horizontal drawing character for the box to the given character.
  • setCDKHistogramLLChar — sets the lower left hand corner of the widget's box to the given character.
  • setCDKHistogramLRChar — sets the lower right hand corner of the widget's box to the given character.
  • setCDKHistogramStatsAttr — sets the attribute to use when drawing the histogram statistics.
  • setCDKHistogramStatsPos — sets where the statistics will be drawn on the widget. see the setCDKHistogram description for more details.
  • setCDKHistogramULChar — sets the upper left hand corner of the widget's box to the given character.
  • setCDKHistogramURChar — sets the upper right hand corner of the widget's box to the given character.
  • setCDKHistogramValue — sets the low, high, and current value of the histogram.
  • setCDKHistogramVerticalChar — sets the vertical drawing character for the box to the given character.
  • setCDKHistogramViewType — sets the view type of the histogram. look at the setCDKHistogram description for more details.

🌸 SEE ALSO 🌸

cdk(3), cdk_binding(3), cdk_display(3), cdk_position(3), cdk_screen(3)

and that's a wrap on part 2, bestie 🫶 this page is from the cdk_histogram(3) manual, dated 2024-03-28 — go forth and draw those bars, you're literally gonna slay ✨💅

📦 where this page comes from