XbaeCaption(3)

📦
version 4.60.4 · 2 versions
, in debian bookworm, debian trixie, ubuntu jammy, ubuntu noble, ubuntu questing, ubuntu resolute, ubuntu stonking

✨ XbaeCaption(3) — Library Functions Manual ✨

okay bestie, gather round, because today we're talking about XbaeCaption — the Bellcore Application Environment (BAE) XbaeCaption widget class. yes, it's a whole manual page in the Library Functions section and yes it's lowkey iconic 💅

🌸 NAME 🌸

XbaeCaption — the Bellcore Application Environment (BAE) XbaeCaption widget class. that's it, that's the name, she's simple and she knows it 🎀

🦋 SYNOPSIS 🦋

#include <Xbae/Caption.h>

one include and you're in, no cap ✨

💖 DESCRIPTION 💖

okay so XbaeCaption is a simple manager whose whole entire job is to associate a label with its single child. that's the assignment. one label, one child, no drama 🙈

the label can be either an XmString or a Pixmap — pick your fighter — and it can be displayed in any one of twelve positions around the edge of the child. twelve!! a whole dozen placements, the versatility is giving main character energy fr fr 👑

XbaeCaption also does geometry management, meaning its size always matches its child's size plus the size of the label and label offset. so you never have to do the math yourself, she handles it, periodt.

and here's the tea: if you use XbaeCaption with an XmFrame child, you can label groups of related widgets in a visually appealing manner. obsessed. it's also useful for associating labels with individual XmTextFields — so like, one field, one cute little label, we love a personalized touch 🌸

🎀 Classes 🎀

XbaeCaption inherits behavior and resources from the Core, Composite, Constraint and XmManager widget classes.

  • the class pointer is xbaeCaptionWidgetClass
  • the class name is XbaeCaption

yes bestie, she comes from a long line of distinguished widget ancestors and she carries all of them with her 💜

🌈 New Resources 🌈

these are the brand new resources XbaeCaption brings to the table. and listen, about the Access codes — they tell you how you're allowed to touch each resource:

  • C — you can set it at creation time
  • S — you can set it with XtSetValues
  • G — you can retrieve it with XtGetValues

now the whole resource set, laid out for you like a lil shopping list 🛍️:

👑 XbaeCaption Resource Set 👑

  • XmNfontList — class XmCFontList, type FontList, default dynamic, access CSG
  • XmNlabelAlignment — class XmCLabelAlignment, type XbaeLabelAlignment, default XbaeAlignmentCenter, access CSG
  • XmNlabelOffset — class XmCLabelOffset, type Int, default 0, access CSG
  • XmNlabelPixmap — class XmCLabelPixmap, type PrimForegroundPixmap, default XmUNSPECIFIED_PIXMAP, access CSG
  • XmNlabelPosition — class XmCLabelPosition, type XbaeLabelPosition, default XbaePositionLeft, access CSG
  • XmNlabelString — class XmCXmString, type XmString, default widget name, access CSG
  • XmNlabelTextAlignment — class XmCAlignment, type Alignment, default XmALIGNMENT_CENTER, access CSG
  • XmNlabelType — class XmCLabelType, type LabelType, default XmString, access CSG

and now, one by one, the lore on each 👇

XmNfontList specifies the font of the text used in the caption label. here's the important bit: if this value is NULL at initialization, it gets initialized by looking up the parent hierarchy of the widget for an ancestor that is a subclass of the XmBulletinBoard, VendorShell or XmMenuShell widget class. and if such an ancestor is found, the font list is initialized to the appropriate default font list of the ancestor widget — that's XmNdefaultFontList for VendorShell and XmMenuShell, and XmNlabelFontList or XmNbuttonFontList for XmBulletinBoard. refer to XmFontList(3X) for more info on the creation and structure of a font list. oh and heads up bestie: this resource is copied. 💅

XmNlabelAlignment specifies the alignment of the caption label along the side of the caption child. it must be one of the enumerated XbaeLabelAlignment types: XbaeAlignmentTopOrLeft, XbaeAlignmentCenter, XbaeAlignmentBottomOrRight. three options, pick one, don't get creative 😌

XmNlabelOffset specifies the offset, in pixels, of the caption label from the caption child. and if the offset is negative, then the caption label will overlap the caption child by that many pixels. so like, negative offset = she's leaning in, they're besties now 🫶

XmNlabelPixmap specifies the caption label pixmap when XmNlabelType is XmPIXMAP. that's the whole thing. 🎀

XmNlabelPosition specifies on which side of the caption child the caption label should be placed. must be one of the enumerated XbaeLabelPosition types: XbaePositionLeft, XbaePositionRight, XbaePositionTop, XbaePositionBottom. four sides, twelve total arrangements, geometry is her passion 💅

XmNlabelString specifies the compound string when the XmNlabelType is XmSTRING. if this value is NULL, it is initialized by converting the name of the widget to a compound string. refer to XmString(3X) for more info on the creation and structure of compound strings. ✨

XmNlabelTextAlignment specifies the text alignment for the caption label. ngl, this resource is only useful for multi line caption labels — single line girlies can scroll past. valid values are:

  • XmALIGNMENT_BEGINNING — left alignment causes the left sides of the lines of text to be vertically aligned
  • XmALIGNMENT_CENTER — center alignment causes the centers of the lines of text to be vertically aligned
  • XmALIGNMENT_END — right alignment causes the right sides of the lines of text to be vertically aligned

XmNlabelType specifies the caption label type. valid values are:

  • XmSTRING — the caption label will display the XmNlabelString
  • XmPIXMAP — the caption label will display the XmNlabelPixmap

text or picture, bestie, that's the choice and honestly both slay 🔥

💜 Inherited Resources 💜

the following resources are the ones XbaeCaption inherits from its superclasses XmManager, Composite and Core. for a complete description of each resource, refer to the man page for that superclass — she's not gonna re-explain her family's whole deal, that's what the family man pages are for 😤

and the Access column codes mean the same thing they did up there: C for set at creation time, S for set using XtSetValues, G for retrieved using XtGetValues. (the actual inherited resource table follows in the next part, so don't go anywhere bestie 🦋)

okay so before we get to the caption's own little resource glow-up, we gotta meet the ✨inherited✨ crew — everything that comes down the family line. The original page puts all of this in big fancy tables, but tables are giving spreadsheet-at-a-family-reunion energy, so imma lay it out as lists. Every name, class, type, default and access code stays exactly where it belongs. No cap. 🫶

Every resource below is listed as: resource name, its class, its type, its default, and its access code — all of them, no skipping, bestie. 💅

👑 XmManager Resource Set 👑

  • XmNbottomShadowColor — class XmCBottomShadowColor, type Pixel, default dynamic, access CSG
  • XmNbottomShadowPixmap — class XmCBottomShadowPixmap, type Pixmap, default XmUNSPECIFIED_PIXMAP, access CSG
  • XmNforeground — class XmCForeground, type Pixel, default dynamic, access CSG
  • XmNhelpCallback — class XmCCallback, type Callback, default NULL, access CSG
  • XmNhighlightColor — class XmCHighlightColor, type Pixel, default dynamic, access CSG
  • XmNhighlightPixmap — class XmCHighlightPixmap, type Pixmap, default dynamic, access CSG
  • XmNnavigationType — class XmCNavigationType, type XmNavigationType, default XmTAB_GROUP, access CSG
  • XmNshadowThickness — class XmCShadowThickness, type Dimension, default 2, access CSG
  • XmNstringDirection — class XmCStringDirection, type XmStringDirection, default dynamic, access CG (yeah bestie, this one's CG, not CSG — she's built different 💅)
  • XmNtopShadowColor — class XmCTopShadowColor, type Pixel, default dynamic, access CSG
  • XmNtopShadowPixmap — class XmCTopShadowPixmap, type Pixmap, default dynamic, access CSG
  • XmNtraversalOn — class XmCTraversalOn, type Boolean, default True, access CSG
  • XmNunitType — class XmCUnitType, type UnsignedChar, default dynamic, access CSG
  • XmNuserData — class XmCUserData, type Pointer, default NULL, access CSG

🦋 Composite Resource Set 🦋

  • XmNchildren — class XmCReadOnly, type WidgetList, default private, access G
  • XmNinsertPosition — class XmCInsertPosition, type Function, default NULL, access CSG
  • XmNnumChildren — class XmCReadOnly, type Cardinal, default 4, access G

and that's the whole inherited buffet, plated and served 🍓 next up we get into the caption's own resources, so stay with me bestie, we're so close to the good part.

🎀 Core Resource Set 🎀

okay bestie, gather round, because this is the entire core resource lineup and we are not skipping a single one 💅. Each bullet goes: name — class, type, default, access. Read it like a menu, except the drinks are X resources and every single one is lowkey iconic ✨.

  • XmNaccelerators — class XmCAccelerators, type AcceleratorTable, default NULL, access CSG
  • XmNancestorSensitive — class XmCSensitive, type Boolean, default dynamic, access CSG
  • XmNbackground — class XmCBackground, type Pixel, default dynamic, access G
  • XmNbackgroundPixmap — class XmCPixmap, type Pixmap, default XmUNSPECIFIED_PIXMAP, access CSG
  • XmNborderColor — class XmCBorderColor, type Pixel, default XtDefaultForeground, access CSG
  • XmNborderPixmap — class XmCPixmap, type Pixmap, default XmUNSPECIFIED_PIXMAP, access CSG
  • XmNborderWidth — class XmCBorderWidth, type Dimension, default 0, access CSG
  • XmNcolormap — class XmCColormap, type Colormap, default dynamic, access CG
  • XmNdepth — class XmCDepth, type Int, default dynamic, access CG
  • XmNdestroyCallback — class XmCCallback, type Callback, default NULL, access CSG
  • XmNheight — class XmCHeight, type Dimension, default dynamic, access CSG
  • XmNinitialResourcesPersistent — class XmCInitialResourcesPersistent, type Boolean, default True, access CG
  • XmNmappedWhenManaged — class XmCMappedWhenManaged, type Boolean, default True, access CSG
  • XmNscreen — class XmCScreen, type Screen, default dynamic, access CG
  • XmNsensitive — class XmCSensitive, type Boolean, default True, access CSG
  • XmNtranslations — class XmCTranslations, type TranslationTable, default internal, access CSG
  • XmNwidth — class XmCWidth, type Dimension, default dynamic, access CSG
  • XmNx — class XmCPosition, type Position, default 0, access CSG
  • XmNy — class XmCPosition, type Position, default 0, access CSG

🦋 Translations 🦋

XbaeCaption is not out here inventing its own choreography, bestie — it inherits its translations from XmManager. Whatever XmManager is doing, that's the vibe. periodt 🫶

🌸 Type Converters 🌸

So besides the standard type converters that Xt and Motif already went and registered (their work, not ours 💅), XbaeCaption registers these extra ones:

  • CvtStringToLabelAlignment() — takes a String and converts it into the enumerated XbaeLabelAlignment type. The strings TopOrLeft, Top and Left all get converted to XbaeAlignmentTopOrLeft. The string Center converts to XbaeAlignmentCenter. And the strings BottomOrRight, Bottom and Right convert to XbaeAlignmentBottomOrRight. Why do we care? Because this converter is literally what lets you specify the XmNlabelAlignment resource in a resource file ✨. Oh and it's case insensitive, so don't panic about your caps.
  • CvtStringToLabelPosition() — takes a String and converts it into the enumerated XbaeLabelPosition type. The string Left converts to XbaePositionLeft. The string Right converts to XbaePositionRight. The string Top converts to XbaePositionTop. The string Bottom converts to XbaePositionBottom. Same energy as above: this is the converter that lets you specify the XmNlabelPosition resource in a resource file 💖. Also case insensitive. no cap.

💜 Public Functions 💜

These are the external entry points to XbaeCaption class methods, and yes we're listing them all:

XbaeCreateCaption()

Widget XbaeCreateCaption()
     Widget     parent;
     String     name;
     ArgList    arglist;
     Cardinal   argcount;
  • parent — specifies the parent widget ID 👑
  • name — specifies the name of the created widget
  • arglist — specifies the argument list
  • argcount — specifies the number of attribute/value pairs in the argument list (arglist)

XbaeCreateCaption() creates an instance of an XbaeCaption widget and hands you back the associated widget ID. that's it, that's the whole function, slay 🔥

🌈 Virtual Bindings 🌈

The bindings for virtual keys are vendor specific — so like, that's a your-vendor question, not a me question 🙈. For the full tea on bindings for virtual buttons and keys, go read VirtualBindings(3X).

👑 AUTHOR 👑

  • Andrew Wason, Bellcore, Piscataway NJ; author (aw@bae.bellcore.com)
  • Andrew Lister (lister@db.com)

⭐ RELEASE ⭐

This document describes XbaeCaption from Xbae Version 4.9.

🦋 SEE ALSO 🦋

ok so if you wanna go deeper (and bestie, you know you do), go bother these other pages, they're the whole friend group:

  • Core(3X)
  • Composite(3X)
  • XmManager(3X)
  • XmLabel(3X)

👑 Notice of Limitation 👑

ok so here's the part where the grown-ups talk. ngl it's a lot of capital letters, but it matters, so let's get into it 💅

Bellcore, plus the previous and current maintainers of the Xbae widgets (together they're calling themselves the 'authors'), are handing you this info only for professionals who already have the right amount of experience to read it and interpret it according to generally accepted engineering standards (or other professional standards) and whatever regulations apply. And no — nothing here is a recommendation about any products or vendors, and you shouldn't read it like it is. 🙈

The info in here was put together from sources they consider reliable, and the authors reserve the right to revise it whenever, without telling you first — but they're under no obligation to do that. Also, unless you've been expressly granted a license by Bellcore in a separate, applicable written agreement with Bellcore, then no license is granted to you — express or implied — under any patents, copyrights or other intellectual property rights. Using this info is entirely your call, and it shall not be deemed an inducement by Bellcore to infringe any existing or later-issued patent, copyrights, or other intellectual property right. 🚫

and then, the part in the big scary letters:

THE AUTHORS MAKE NO REPRESENTATIONS AND EXTENDS NO WARRANTIES, EXPRESS OR IMPLIED, WITH RESPECT TO THE INFORMATION, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR ANY PARTICULAR PURPOSE, AND THE WARRANTY AGAINST INFRINGEMENT OF PATENTS OR OTHER INTELLECTUAL PROPERTY RIGHTS. THE INFORMATION IS PROVIDED ``AS IS'', AND IN NO EVENT SHALL THE AUTHORS OR ANY OF ITS AFFILIATES BE LIABLE FOR ANY DAMAGES, INCLUDING ANY LOST PROFITS OR OTHER INCIDENTAL OR CONSEQUENTIAL DAMAGES RELATING TO THE INFORMATION.

so yeah — no promises, no warranties, no taking them to court over lost profits or incidental or consequential damages. it's giving "as is" and that's the whole vibe. 😭

The copyright situation, laid out:

  • Copyright 1991 Bellcore. All Rights Reserved.
  • Copyright 1995-99 Andrew Lister All Rights Reserved.
  • Copyright 1999-2002 LessTif Developers

and the no-warranty thing above covers all the additions and contributions too. No contributor shall be held liable; this work is provided ``as is''. And fr fr, if that's a problem for you? Then don't use this software. 🫶

and that's a wrap bestie!! 🎀 this page came from xbae, version 4.60.4, and it's the XbaeCaption(3) manual page. go forth and caption things, you absolute icon 👑✨💖

📦 where this page comes from