The XBanner Resource Reference

For XBanner v1.3


-

Table of Contents

General Options Miscellaneous Effect-Specific Resources
Information And Debugging Options Other Effects Specific Options
Background Effects Miscellaneous Resources
Underlining The Text Other Command Line Switches
Putting An Image On The Screen Program Class And Program Name Hints
The Glint Feature Outline Effects - Detailed Information
Color Cycling Options Underline Effects - Detailed Information
PlasmaCloud Effects Explanations About Resource Types

Click here to see the index.

-

General Options

ResourceClass
Type
Description
.label .Label
String
The label is the text that XBanner draws on the root window. It may be any text. All text is drawn on one line.

You can use double-quotes (e.g. " ") for leading spaces.

Also, you can use environment variables within the label. Use $VAR_NAME or ${VAR_NAME} to insert environment variable values into the label. To get a single $ sign, use $$.

Command-line: -label.

.effect .Effect
Keyword
The graphics rendering to be done on the text of .label.
Command-line: -effect. This is a keyword resource.
Valid values:
3D-Shadow
Take Shadowed-Outline, and use it for both the main text and its shadows. You can use .shadows to control the number of shadows. The outline for the "shadows" is chosen by .shadowColor.
Backlight
The text is outlined with 1-pixel outlines, colored along a color-gradient. Use .thickness to select number of outlines, and .backlightGrad for the gradient.
Coin
This is very much like StandOut but it has the first few pixels closest to the text with oposite colors, creating a sort of a rim resembling the rim of a coin.
Fade
This effect is very much like the Thick effect, only that here the pixels of the thickness of the text change along a color-gradient. If you select the color gradient such that the furthest color from the text is the same color as the background, it seems as if the text fades into the background. Use .fadeGrad to select the color gradient.
FatText
The outlines are like in Backlight, but go into the letters, causing them to look fat if the colors are properly selected. Use .thickness to select number of "out"lines, and .fatTextGrad for the gradient.
FgGrad
This is like Shadow but the pixels of the text are colored along a color gradient from the top line of pixels to the bottom. Use .fgGradGrad to select the color gradient for this effect.
FgPlasma
The text is seen to be like a window into an area filled with a PlasmaCloud. Use .fgPlasmaNCol to select number of colors for the PlasmaCloud. The color gradient of the PlasmaCloud can be selected with .fgPlasmaGrad, and the graininess factor for the FgPlasma effect can be set with .fgPlasmaGrain.
FunnyOutline
Like taking a marker and coloring the outermost line of the letters from the inside. Only wide parts of the font keep their original color, and the outcome is somewhat like an outline. Here the .hiColor resource selects the outline color.
None
No effect. Text is drawn as it is.
Outline
Text appears with an outline. Use the .hiColor resource to select the color of the outline.
PopArt
The text is surrounded by 1-pixel wide outlines with their colors alternating between .hiColor and .shadowColor. The number of outlines is selected by the .thickness resource.
Shadow
Simple shadow under the text. Use .shadowColor. Use .shadowXOffset and .shadowYOffset to control location of the shadow under the text.
Shadowed-Outline
Combination of Shadow and Outline.
Shake
Lines of pixels in the same color as the text are drawn at 3 pixels and 6 pixels above the text giving it a sense of shaking. This can create the infamous "NERVOUS? TENSE? TIRED?" sign.
StandOut
The text seems to have a frame like that of Motif buttons, with shading which makes it stand out of the surrounding background. The upper and left sides are colored by .hiColor and the bottom and right sides are colored by .shadowColor.
StandIn
This is like StandOut but with the colors inverted.
StandOut2
Same as StandOut but the effect is rendered into the letters, rather than outside. This is great for unspaced text.
StandIn2
Same as StandIn but the effect is rendered into the letters, rather than outside. This is great for unspaced text.
Thick
Like Outline but instead of a shadow, the letters have a visible thickness. Use .thickness to control thickness of letters in pixels.
.font .Font
String
This is the font to be used for the text you chose with .label. Click here for some hints on finding fonts.
Command-line: -font.
.placement .Placement
Keyword
This resource governs where the text will be placed on the screen. You can choose any of the following:
   TopLeft     TopCenter      TopRight
   
                 Center

   BottomLeft BottomCenter BottomRight
As well as XY and CenteredOnY.
When using XY, use .x and .y to choose the location of the text.
When using CenteredOnY, only .y affects the location, and the text is centered on that Y position.
You can use .showCalc to help you choose where to place your text.
Command-line: -placement.

-

Information And Debugging Options

ResourceClass
Type
Description
.showErrors .ShowErrors
Boolean
Display error and warning information by drawing it, black text on white background on the root window. The line is placed in the top left corner. This is a boolean resource.
Command-line: -showerr and -noshowerr.
.showCalc .ShowCalc
Boolean
This prints out to standard error information about the size and position of the text's bounding box. This may be useful in selecting placement of a second line of text by running XBanner twice. This is a boolean resource.
Command-line: -showcalc and -hidecalc.
.dumpRes .DumpRes
Boolean
This boolean resource will tell XBanner to write to a file the list of all resources it sees, after having merged in all different sources, like the app-deafults file, the .Xdefaults, etc.
Command-line: -dumpres and -nodumpres.
.dumpResFile .DumpResFile
String
This is the file name for the .dumpRes resource.
Command-line: -dumpresfile.

-

Background Effects

ResourceClass
Type
Description
.bgStyle .BgStyle
Keyword
This is a keyword resource which selects what type of background you want. Most of these background style use the .bgGrad and .bgGradRepeat to select the color gradient, and .barSize to determine the number of colors in the gradient as a function of the thickness of each element in the gradient.
Command-line: -bgstyle.
Valid values:
BgPix
This tiles a pixmap (.XPM file) over the root window. Use .bgPixFile to select the pixmap file.
Fan
This draws a nice fan, whose center is at the center of the bottom pixel line of the screen.
Fill
This simply fills the background with a single color determined by the .bgFillColor resource.
LeftDiagonal
This fills the background with a color gradient going from the top-left corner to the bottom right.
LeftRight
Fills the screen with a color gradient going from the left side to the right.
LeftSplit
Like two small Fan effects one centered on the top-left corner and the other on the bottom-right corner of the screen.
None
No background rendering will be done.
Plasma
This will fill the bacground with a PlasmaCloud. Use .plasmaNumColors and .plasmaGraininess to select number of color and the graininess factor for the PlasmaCloud.
RightDiagonal
Same as LeftDiagonal, but the gradient is going from the top-right corner to the bottom left.
RightSplit
Same as LeftSplit but the little fans are centered on the top-right corner and bottom-left corner.
Ripples
Draws intersecting circles that (when color cycled) look like ripples in a pond.
TopDown
The color gradient goes from top to bottom.
.bgFillColor .BgFillColor
ColorSpec
This is the color used for the filling the background if requested by the Fill background style or the .bgFill resource. This is a color resource.
Command-line: -bg.
.bgGrad .BgGrad
GradSpec
This is a color gradient resoruce which determines which colors are the anchor colors of the background rendering effects.
Command-line: -bggrad
.bgGradRepeat .BgGradRepeat
Numeric
This is a numerical resource which causes XBanner to use a smaller number of colors for the background gradient, but use these colors several times.
This resource must be a positive integer.
Command-line: -bggradrep
.autoFillBg .AutoFillBg
Boolean
This will cause XBanner to do a background fill before any of the background style (except None of course, Fill and BgPix). This resource takes precedence over .bgFill.
Command-line: -autofill and -noautofill
.bgFill .BgFill
Boolean
This resource is just like .autoFillBg but you specifiy the color by .bgFillColor.
Command-line: -bgfill and -nobgfill
.barSize .BarSize
Numeric
This resource governs the amount of colors allocated for the background effects (not including BgPix, Fill, None and Plasma). For instance, the TopDown background style is drawn by drawing a set of bars from top to bottom each in a different color. .barSize selects the size of these bars in pixels. The Fan background style is drawn by drawing triangles with one vertex at the center of the fan, and the distance between the other two vertices, which are both on the side of the screen or on top, is controlled by the .barSize resource.
Command-line: -barsize or -bs
.bgPixFile .BgPixFile
String
This is simply the name of the .XPM file to be used for the BgPix background style.
Command-line: -bgpixfile
.ripples .Ripples
Numeric
Selects the number of circles to draw for the Ripples background. Best values are 2 and 3.
.rippleColors .RippleColors
Numeric
This is the number of colors to use for the Ripples background.

-

Underlining The Text

ResourceClass
Type
Description
.underlined .Underlined
Boolean
This boolean resource determines if the text will be underlined.
Command-line: -underline or -ul, and -noul
.underlineColor .UnderlineColor
ColorSpec
This is the color of the underline. The word FGC is a special keyword that causes XBanner to use the same color for the underline as for the text. This also causes the following rendering effects to be rendered on the underline as well: Backlight, Coin, Fade, FatText, FgGrad, FgPlasma, FunnyOutline, PopArt, Shadow, Shadowed-Outline, Shake, StandOut, StandIn, StandOut2, StandIn2, Thick.
Command-line: -ulcolor
.underlineThickness .UnderlineThickness
Numeric
This numerical value (which must be positive) determines the number of pixels width of the underline.
Command-line: -ulthick

-

Putting An Image On The Screen

ResourceClass
Type
Description
.doPixmap .DoPixmap
Boolean
This is a boolean resource which determines whether or not you want a pixmap file put on the screen. If the pixmap file (.XPM file) uses the None color, XBanner will honor it.
Command-line: -dopixmap and -nopixmap
.pixFile .PixFile
String
This is the name of the pixmap file (.XPM) to be put on the screen. If this file name begins with a @ sign, then this is the name of a pixmap-list file. The pixmap-list file contains a line for each pixmap to display, and the location where to display it.
Example:

XBanner.pixFile: @/usr/local/etc/pix_names.lst

File: /usr/local/etc/pix_names.lst
/usr/local/lib/pixmaps/Linux_Penguin.xpm 0 600
/usr/lib/3D-Pixmaps/Sponsors.xpm 800 760
.pixmapX .PixmapX
Numeric
The X position of the pixmap on the screen.
.pixmapY .PixmapY
Numeric
The Y position of the pixmap on the screen.

-

The Glint Feature

ResourceClass
Type
Description
.glint .Glint
Boolean
A boolean resource to turn the Glint feature on or off. This implies .linger: True.
Command-line: -glint and -noglint
.glintSpeed .GlintSpeed
Numeric
This numerical resource governs the speed of each glinting star appearing on your text. There are 3 different groups of values:
  • Positive values make for faster and faster glints, which use up less CPU time and less network bandwidth.
  • A value of zero (0) is the fastest, and is actually a "blink" of the glint star. You can change this speed by editing xbanner.h and changing the definition of BLINK_SPEED_TIME.
  • Negative values mean slower and slower glints.
Command-line: -glintspeed
.glintMin .GlintMin
Numeric
This resource is the smallest size of glint you would like in pixels. The Glint feature makes glints whose size is randomly chosen between this value and .glintMax.
Command-line: -gmin
.glintMax .GlintMax
Numeric
See .glintMin.
Command-line: -gmax
.glintTimeMin .GlintTimeMin
Numeric
This is the shortest amount of time between glints. XBanner will wait a random time between glints, which is at least .glintTimeMin milliseconds long, and not longer than .glintTimeMax ms.
Command-line: -gtimemin
.glintTimeMax .GlintTimeMax
Numeric
See .glintTimeMin
Command-line: -gtimemax
.cornerMask .CornerMask
Keyword-list
The corner-mask is a comma separated list of keywords (see below) that describes which corners you allow / forbid XBanner to glint on. The default is all corners. Evaluation is done from left to right.
Keywords:
All
All corners.
DownLeft
Add Down-Left corners.
DownRight
Add Down-Right corners.
NoDownLeft
Remove Down-Left corners from the mask.
NoDownRight
Remove Down-Right corners from the mask.
NoUpLeft
Remove Up-Left corners from the mask.
NoUpRight
Remove Up-Right corners from the mask.
UpLeft
Add Up-Left corners.
UpRight
Add Up-Right corners.
Command-line: -cornermask

-

Color Cycling Options

ResourceClass
Type
Description
.cycleColors .CycleColors
Keyword-list
This is a comma separated list of keywords, each signifying a component you want to have color-cycling done on. This implies .linger: True.
Command-line: -cycle
Valid keywords:
Backlight
Cycle the colors of the Backlight effect.
BG
Cycle the colors of the background. This does not work for the BgPix, Fill and None background styles.
Fade
Cycle the colors of the Fade effect.
FatText
Cycle the colors of the FatText effect.
FG
Continually change the color of the main text along a color gradient. This can be done on any effect, but of course it will have no effect on FgPlasma, and, depending on .thickness, it might have no effect on FatText, StandOut2 and StandIn2. Use .fgCycleGrad to select the color gradient.
FgGrad
Cycle the colors of the FgGrad effect's color gradient.
FgPlasma
Cycle the colors of the FgPlasma effect.
None
No color-cycling.
.reverseCycle .ReverseCycle
Keyword-list
This is a comma-separated list of keywords telling which cycling components should be cycled in reverse direction. for a list of the keywords see .cycleColors.
Command-line: -cycrev
.forwardCycle .ForwardCycle
Keyword-list
This is a comma-separated list of keywords telling which cycling components should be cycled in forward direction. for a list of the keywords see .cycleColors.
Command-line: -cycfor
.cycleSpeed .CycleSpeed
Numeric
This numerical resource selects the speed for the color cycling. This is currently uniform for all cycling components. This value is actually a divisor to the value passed to the usleep() function, hence it is not linear but suffers greatly from the overhead of the rest of the operations done around it. Be warned that faster color-cycling means much larger CPU time consumption! This value must be positive.
Command-line: -cycspeed

-

PlasmaCloud Effects

ResourceClass
Type
Description
.plasmaNumColors .PlasmaNumColors
Numeric
This is the number of colors used when making the Plasma background style. Notice that this resource together with .plasmaGraininess define the smoothness of the PlasmaCloud effect, though it is better to choose a higher graininess factor than a lower number of colors to get a less smooth effect.
Command-line: -plncol
.plasmaGraininess .PlasmaGraininess
Float
This is a floating-point value which must be positive, and chooser the graininess factor for the PlasmaCloud.
Command-line: -plgrain
.fgPlasmaNCol .FgPlasmaNCol
Numeric
This is the number of colors to use for the FgPlasma rendering effect.
Command-line: -fgplncol
.fgPlasmaGrain .FgPlasmaGrain
Float
This is the graininess factor for the FgPlasma rendering effect. This value must be positive.
Command-line: -fgplgrain
.fgPlasmaGrad .FgPlasmaGrad
GradSpec
This is the color gradient of the FgPlasma effect.
Command-line: -fgplgrad

-

Miscellaneous Effect-Specific Resources

ResourceClass
Type
Description
.shadows .Shadows
Numeric
This sets the number of 'shadows' under the main text in the 3D-Shadow effect. This resource must be positive.
Command-line: -shadows
.fgCycColors .FgCycColors
Numeric
This is the number of colors for the FG cycling effect. Must be positive.
Command-line: -fgcyccols
.backlightGrad .BacklightGrad
GradSpec
This determines the color-gradient for the Backlight effect. The first color in the specification is furtherst from the letters. So if you want to see why it is called Backlight, try a FG color of black, on a DarkBlue screen, and use .backlightGrad: darkblue,cyan.
Command-line: -bkltgrad
.fadeGrad .FadeGrad
GradSpec
This is the color gradient for the Fade effect. Again, the first color is furthest from the letters. To gain best results, make the first color in the specification be very very close to the color of the background around the letters.
Command-line: -fadegrad
.fatTextGrad .FatTextGrad
GradSpec
This is the color gradient for the FatText effect. Here the first color is the inner color.
Command-line: -ftgrad
.fgGradGrad .FgGradGrad
GradSpec
This is the color gradient for the FgGrad effect. Here the first color in the specification is near the top of the text.
Command-line: -fggrad
.fgGradBarSize .FgGradBarSize
Numeric
This numeric resource determines how many pixel-lines of the FgGrad effect's main text should use each color, hence deciding the number of colors used for this effect.
Command-line: -fggradbs
.fgCycleGrad .FgCycleGrad
GradSpec
This is the color gradient used for the FG cycling effect.
Command-line: -fgcycgrad

-

Other Effects Specific Options

ResourceClass
Type
Description
.foreground .Foreground
ColorSpec
This is the main color for the text, and initial color for most things.
Command-line: -fg
.shadowColor .ShadowColor
ColorSpec
This is the color of the shadow for the following effects: FatText, FgGrad, FgPlasma, Shadow, and Shadowed-Outline. This also selects the color of the outlines of the various shadows of the 3D-Shadow. Also, this selects the right and bottom colors for the StandOut/In/Out2/In2 effects.
Command-line: -shadowcol or -sc
.hiColor .HiColor
ColorSpec
This selects the color of the outline in Outline effect, the outline color of the main text in 3D-Shadow, the colors for the left and top sides of the text in StandOut/In/Out2/In2.
Command-line: -hicolor or -hc
.thickness .Thickness
Numeric
This selects the thickness of the following effects: Backlight, Coin, Fade, FatText, FunnyOutline, PopArt, StandOut/In/Out2/In2, Thick. Notice that while it is obvious what .thickness means for some of the effects, it is not obvious for others. For the FatText and StandIn/In2, the .thickness selects the number of pixels along the letters' edge and into the letter that XBanner will draw. This is also true for FunnyOutline.
Command-line: -thickness
.shadowXOffset .ShadowOffset
Numeric
(common class)
This resource, which may be negative selects the X offset of the shadow under the text, for those effects that have a shadow: 3D-Shadow, FatText, FgGrad, FgPlasma, Shadow, Shadowed-Outline. Negative values will cause the shadow to appear on the left.
No command-line switch, see .ShadowOffset.
.shadowYOffset .ShadowOffset
Numeric
(common class)
This resource, which may be negative selects the Y offset of the shadow under the text. See .shadowXOffset
No command-line switch, see .ShadowOffset.
Common Class .ShadowOffset
Numeric
This common classname selects how far left and down from the main text the shadow will appear. It simply sets both .shadowXOffset and .shadowYOffset.
Command-line: -shdoffset
.surroundMin .Surround
Numeric
(common class)
This selects the offset to the left and up from the main text where the outline will start. See .Surround for detailed description.
No command-line switch, see .Surround.
.surroundMax .Surround
Numeric
(common class)
This selects the offset to the right and down from the main text where the outline will start. See .Surround for detailed description.
No command-line switch, see .Surround.
Common Class .Surround
Numeric
This resource selects how the oultline will look. Outlines are done by simply drawing the text in the outline's color, in severak locations surrounding the position of the text. If this resource is set to 1, then the text will be drawn in the outline's color one pixel left-up, up, right-up, left, right, left-down, down, right-down from the main text. You can use a .surroundMin value of 1 and a .surroundMax value of 6 to generate asymetric outlines. This resource affects the following effects: Outline, Shadowed-Outline, 3D-Shadow.
Command-line: -surround

-

Miscellaneous Resources

ResourceClass
Type
Description
.x .X
Numeric
This selects the X position of the text for the XY placement type.
Command-line: -x
.y .Y
Numeric
This selects the Y position of the text for the XY, and CenteredOnY placement types.
Command-line: -y
.defXOffset .DefOffset
Numeric
(common class)
This selects a minimum distance from the left / right sides of the screen where the text is allowed to be. This resource mainly guards against trying to draw outside the screen.
No command-line switch.
.defYOffset .DefOffset
Numeric
(common class)
This selects a minimum distance from the top / bottom of the screen where the text is allowed to be. This resource mainly guards against trying to draw outside the screen.
No command-line switch.
Common Class .DefOffset
Numeric
This selects both .defXOffset and .defYOffset in one resource.
No command-line switch.
.linger .Linger
Boolean
This is a boolean resource telling XBanner to leave behind a process with an open display to the X server, and wait until the 'freetemp' utility is run. This helps a lot if you want to run XBanner behind a Chooser window for XDMCP over to X-Terminals and such. Since the Chooser will open the display after the Xsetup script is done, the X server will see no clients, and reset! This option will prevent this.
Command-line: -linger

-

Other Command Line Switches

SwitchMeaning
-hSimple help and version information.
-vSame as -h.
-helpDisplays a detailed list of command-line switches to stdout.
-displayThe display to work with.
-fileUse a specified resource file.
-xrmUse this option to quote any X resource that XBanner recognizes.

-

Program Class Name Hints

The program class is XBanner, and the program name is the name of the binary. This means that if you make a link to xbanner and call it mybanner then you can use two resources like:
mybanner.thickness:	9
XBanner.thickness:	5
and when you run xbanner, you will get a thickness of 5, but if you run it as mybanner the thickness will be 9!
-

Outline Effects - Detailed Information

All outline effects use the .surroundMin and .surroundMax resources. But you can set both of them together using their common class name - XBanner.Surround. In general, the outlining is done by drawing the text in the shadow color first a bit to the left and up, and work your way on all the directions. This means that if .surroundMin is -1, .surroundMax is 2, and the text should be placed at some X,Y location, the outline will be drawn at:
(X-1,Y-1), (X,Y-1), (X+1,Y-1), (X+2,Y-1), (X-1,Y), . . . , (X+2,y+2).
This was done mainly because I wanted to enable unbalanced outlines on the axis going from top-left to down-right. This does not pertain to the FunnyOutline effect.

-

Underline Effects - Detailed Information

The .underlined resource is a boolean that enables underlining of the text drawn by XBanner. You can choose a color name / RGB and set it with the .underlineColor resource, but the best is to set this to FGC which is a special keyword. XBanner recognizes this special name and uses the FG color for the underline. This means that the effects will get rendered on the underline as well. You can choose the line thickness with the .underlineThickness resource.

-

Images On The Root Window

Currently, only pixmap files are supported. I plan to add .GIF support, for GIF89a version, since this version (like .XPM) has an option to specify a transparent color. The pixmap pasted on the screen uses the None color specification in the pixmap file. You can also use an image to be tiled over the entire root window. See the BgPix background style.

I have supplied a version of Larry Ewing's Penguin Linux Logo in .XPM format with the background set to None so it is useable with XBanner! Another version with a colormap reduced to 32 colors is also supported. See the demo for the use of pixmaps.

-

Notes And Explanations Of Different Types Of Resources

  1. Numeric resources are integer numbers.
  2. Float resources are simple notation floating-point numbers. Use XX.YY notation only.
  3. Boolean resources are also not case-sensitive and can accept the values: True, False, Yes, No, On, Off, 1, 0. It should be noted that if you use -file to load a resource file, and that resource file specifies a certain boolean value, then you can override it with another commandline option. Hence using -bgstyle None will definitely make XBanner not render any background.
  4. Keyword resources are not case sensitive. Using XBanner.effect: fgplasma is the same as using XBanner.effect: FgPlasma. This is true for the keywords to command-line switches as well: -effect Coin is the same as -effect COIN. (Be careful, the switches themselves ARE case sensitive in Unix, so -Effect is not -effect!).
  5. Keyword lists are simply a comma-separated list of keywords. Some resources take this type of value, like .cycleColors.
  6. Color resources are simply a name of a color, or a color RGB representation. You can use either #RRGGBB or #RRRRGGGGBBBB.
  7. Color gradients are simply a comma-separated list of color resources. The limit is currently 8 colors per gradient and can be changed through editing xbanner.h and changing the MAX_COLORS_PER_GRAD definition. Here's an example:
    XBanner.BgGrad: Red,#00C276,Blue,Green,#000010AC5F42

Alphabetical Index Of Resources

Common Classes

Resources

- A - .fgCycColors .placement
.autoFillBg .fgCycleGrad .plasmaGraininess
- B - .fgGradBarSize .plasmaNumColors
.backlightGrad .fgGradGrad - R -
.barSize .fgPlasmaGrad .reverseCycle
.bgFill .fgPlasmaGrain .rippleColors
.bgFillColor .fgPlasmaNCol .ripples
.bgGrad .font - S -
.bgGradRepeat .foreground .shadowColor
.bgPixFile .forwardCycle .shadowXOffset
.bgStyle - G - .shadowYOffset
- C - .glint .shadows
.cornerMask .glintMax .showCalc
.cycleColors .glintMin .showErrors
.cycleSpeed .glintSpeed .surroundMax
- D - .glintTimeMax .surroundMin
.defXOffset .glintTimeMin - T -
.defYOffset - H - .thickness
.doPixmap .hiColor - U -
.dumpRes - L - .underlineColor
.dumpResFile .label .underlineThickness
- E - .linger .underlined
.effect - P - - X -
- F - .pixFile .x
.fadeGrad .pixmapX - Y -
.fatTextGrad .pixmapY .y

Back to documentation index.
Back to top.

[email]Please email me for any comments.