OLGX - Application Programmer Interface

1.0  Introduction

This document defines functions for OPEN LOOK Graphics Package (OLGX). OLGX is a 
library for rendering OPEN LOOK items such as scrollbars, buttons, etc.  Most application 
programmers will probably have no need to use the OLGX library unless they want to 
write extensions to the XView toolkit and/or want to render an OPEN LOOK item.

2.0  Initialization Functions

OLGX initialization consists of setting initial graphical information used in rendering (the 
graphics information structure is called Graphics_info, henceforth referred to as ginfo). 
Ginfos contain the values which define graphical characteristics. These characteristics in-
clude pixel values, text fonts, and glyph fonts. As you can see, the ginfo is the mechanism 
by which graphics information is passed between clients and OLGX. Macros are provided 
to access the members of the ginfo struct, because the ginfo struct is intended to be opaque. 
Clients should NOT copy the ginfo struct or try to access its members directly

Each ginfo has 9 or less graphics contexts (GCs), depending on whether 2D or 3D is spec-
ified. However, in order to save memory and reduce overhead, ginfos will share graphic 
contexts with other ginfos. 

The following describes the OLGX initialization functions.

Graphics_info *
     olgx_main_initialize(display, screen, depth, d_flag, glyphfont_struct, textfont_struct, 
	pixvals, stipple_pixmaps)

	Display 	*display;
	int 	screen;
	unsigned int 	depth;
	int 	d_flag;
	XFontstruct	glyphfont_struct; 
	XFontstruct	textfont_struct;
	unsigned long	pixvals[ ];
	Pixmap	stipple_pixmaps[ ];

olgx_main_initialize() creates and initializes a graphics information structure. display is a 
pointer to the display structure associated with an active server connection. screen is the 
desired screen. depth is the depth of the window. d_flag may be one of the following flags:

OLGX_2D	Two dimensional rendering.

OLGX_3D_COLOR	Three dimensional rendering on color screen.

glyphfont_struct is the XFontstruct of the desired glyphfont. textfont_struct is the XFont-
struct of the desired text font. pixvals is an array of five pixel values. The colors associated 
with each element of pixvals are OLGX_WHITE (0), OLGX_BLACK(1), OLGX_BG1 
(2), OLGX_BG2 (3) and OLGX_BG3 (4). In a monochrome environment, only white and 
black need to be set. The application must maintain the colormap and allocate the colors 
properly. In 3D mode, applications are encouraged to use olgx_calculate_3Dcolors() to 
get the OLGX_BG2, OLGX_BG3, and OLGX_WHITE pixel values. Please refer to the 
OPEN LOOK specifications for further details on these colors. stipple_pixmaps[ ] is ig-
nored.

olgx_initialize() still exists for backward compatibility reasons.



void
olgx_destroy(ginfo)

	Graphics_info *ginfo;

olgx_destroy() destroys an existing Graphics_info structure info. In the process, olgx_de-
stroy() will free up any server resources that OLGX has associated with the specified ginfo 
and not shared by other ginfos. 

void
olgx_calculate_3Dcolors(fg, bg1, bg2, bg3, white)

	XColor 	*fg, *bg1;
	XColor	*bg2, *bg3, *white;	/* Return values */

olgx_calculate_3Dcolors() is a utility function which calculates a pleasant combination of 
bg2, bg3, and white (highlight) color values given the fg (foreground) and bg1 (back-
ground) values. The calculation adheres to the OPEN LOOK specification.

fg, bg1, bg2, bg3, and white are pre-allocated XColor structs with fg and bg1 initialized 
with the appropriate foreground and background pixel values. On the return, bg2, bg3, and 
white XColor structs are initialized with the OPEN LOOK specified values.

3.0  Manipulation Functions

void
 olgx_set_text_font(ginfo, font_struct, flag)

 	Graphics_info 	*ginfo;
 	XFontstruct	font_struct;
	int	flag;

olgx_set_text_font() sets the current text font. ginfo is a pointer to the Graphics Informa-
tion Structure. font_struct is the XFontstruct of the desired text font. flag may be one of the 
following:

OLGX_NORMAL	The changed text font will be reflected only in the specified ginfo. 
Other ginfos that share graphic contexts with the specified ginfo will 
not be affected.

OLGX_SPECIAL	Changes the ginfo without checking whether it is shared or not. The 
advantage of this is that it does not have the overhead of checking if 
GCs are shared or not, or creating new GCs. The disadvantage is that 
this change may also affect other ginfos that share the GCs. It is up to 
the client to restore the values so that the changed text font does not 
affect the other ginfos.

Subsequent text operations using ginfo will use this font.



void
olgx_set_glyph_font(ginfo, glyphfont_struct, flag)

	Graphics_info *ginfo;
	XFontstruct glyphfont_struct;
	int flag;

olgx_set_glyph_font() sets the current glyph font. Subsequent graphics operations using 
ginfo will use this glyph font. ginfo is a pointer to Graphics_info. glyphfont_struct is the 
XFontstruct of the desired glyph font. flag may be one of the following:

OLGX_NORMAL	The changed glyph font will be reflected only in the specified ginfo. 
Other ginfos that share graphic contexts with the specified ginfo will 
not be affected.

OLGX_SPECIAL	Changes the ginfo without checking whether it is shared or not. The ad-
vantage of this is that it does not have the overhead of checking if GCs 
are shared or not, or creating new GCs. The disadvantage is that this 
change may also affect other ginfos that share the GCs. It is up to the 
client to restore the values so that the changed glyphfont does not affect 
the other ginfos.



void
olgx_set_single_color(ginfo,index,pixval,flag)

	Graphics_info * ginfo;
	unsigned long pixval;
	int index;
	int flag;

olgx_set_single_color() sets the color of the index member of the five element array of 
colors contained in ginfo to the specified pixel value pixval. index can be any one of the 
five members of the array namely OLGX_WHITE (0), OLGX_BLACK (1), OLGX_BG1 
(2), OLGX_BG2 (3), or OLGX_BG3 (4).   flag may be one of the following:

	OLGX_NORMAL	The changed color will be reflected only in the specified ginfo. Other 
ginfos that share graphic contexts with the specified ginfo will not be 
affected.

	OLGX_SPECIAL	Changes the ginfo without checking whether it is shared or not. The ad-
vantage of this is that it does not have the overhead of checking if GCs 
are shared or not, or creating new GCs. The disadvantage is that this 
change may also affect other ginfos that share the GCs. It is up to the 
client to restore the values so that the changed color does not affect the 
other ginfos. OLGX_SPECIAL might be used where XView renders an 
array of color choice items representing a palette where each choice 
item is rendered by changing the foreground color.



unsigned long
 olgx_get_single_color(ginfo,index)

	Graphics_info * ginfo;
	int index;

olgx_get_single_color() returns the pixel value of the index member of the five element 
array of pixel values stored in ginfo. index can be any one of the five members of the array 
namely OLGX_WHITE (0), OLGX_BLACK (1), OLGX_BG1 (2), OLGX_BG2 (3), or 
OLGX_BG3 (4).

4.0  Rendering Functions

void
olgx_draw_button(ginfo, win, x, y, width,height, label, state)

	Graphics_info *ginfo; 
	Window win;
	int x, y, width;
	int height;
	void *label;
	int state;

This function renders panel buttons and menu items. win is the window in which the object 
is to be rendered. x and y are the coordinates of the upper left-hand corner of the object, 
relative to the upper left-hand corner of win. width is the width of the entire object, includ-
ing the button endcaps if the object is a panel button. The label of a button can either be a 
character string or an X pixmap. If the label is a character string, label is a pointer to a 
character. If the label is an X pixmap, label is a pointer to the struct Pixlabel. The struct 
Pixlabel is explained below and is to be initialized appropriately. If the given label is too 
large to fit in the button, it will be clipped appropriately. height is the height of the button 
and is used only when the button label is a pixmap. If the label is not a pixmap, then the 
height should be 0, in which case the button height is determined from the button glyphs. 
state is the bitwise OR of a set of flags representing the current state of the object. These 
flags are as follows:

OLGX_NORMAL 	The item is not invoked. This is the default.

OLGX_INVOKED 	Item is invoked. In 3D, it is drawn as a recessed button 
or menu item. In 2D, the item is in reverse video.

OLGX_MENU_ITEM 	This object is a menu item, not a panel button. With 
this flag, no outline is drawn on non-invoked items.

OLGX_ERASE 	The background behind the item is to be cleared be-
fore the item is drawn.This flag is only valid for trans-
parent items such as non-invoked menu items.

OLGX_BUSY 	The item is busy. In either 2D or 3D, this means that it 
will be filled with a 15% grey stipple.

OLGX_DEFAULT 	This item is a default item. OLGX will render it item 
with a default ring.

OLGX_INACTIVE	Designates the item as inactive. It will be drawn with a 
50% grey stipple.

OLGX_VERT_MENU_MARK	The item contains a vertical menu mark.

OLGX_HORIZ_MENU_MARK	The item contains a horizontal menu mark.

OLGX_LABEL_IS_PIXMAP 	By default, item labels are strings. This flag must be 
presented if the label is a pixmap or window ID.

	Struct Pixlabel{
		XID	pixmap;
		int	width;	/* width of the pixmap */
		int	height;	/* height of the pixmap */
	}

Note: If the label is a pixmap, the width of the button is always incremented by 
OLGX_VARHEIGHT_BTN_MARGIN which accommodates the space for a de-
fault ring around the pixmap in case OLGX_DEFAULT is set.



void
olgx_draw_abbrev_button(ginfo, win, x, y, state)

	Graphics_info *ginfo; 
	Window win; 
	int x, y, state;

This function renders an abbreviated menu button at the position (x, y) with in window 
win. state may be OLGX_NORMAL, OLGX_INVOKED, OLGX_INACTIVE or 
OLGX_BUSY. Use OLGX_ ERASE to clear the underlying previous state. The Menu-
Mark drawn inside the button points down.



void 
olgx_draw_slider(ginfo, win, x, y, width, old_value, new_value, state)

	Graphics_info *ginfo; 
	Window win; 
	int x, y, width, old_value, new_value, state;

olgx_draw_slider() renders or updates a slider. The slider will be drawn within window 
win at location (x, y). width represents the width of the slider in pixels, including endcaps. 
old_value and new_value give the old and new values of the slider in pixels with the ori-
gin at either the top or the left of the slider. Finally, state gives information about the cur-
rent state of the slider. It consists of the bitwise-OR of any of the following flags:

OLGX_VERTICAL 	The slider is a vertical slider.

OLGX_HORIZONTAL 	The slider is a horizontal slider.

OLGX_UPDATE 	Update the slider instead of rendering the whole slider. If 
OLGX_ UPDATE is not specified, the parameter old_value 
will not be used.

This function does not draw any of the text associated with the OPEN LOOK sliders. For 
example, some OPEN LOOK sliders provide tick marks, end boxes, labels on the tick 
marks and numeric-entry fields beside the slider. Handling these is left to the application.



void
olgx_draw_resize_corner(ginfo, win, x, y, type, state)

	Graphics_info *ginfo;
	Window win;
	int x, y, type;
	int state;

This function places a resize corner of the requested type in a given location. (x, y) and win 
specify the location and window of the resize corner, respectively. The shape of the resize 
corner is determined by the type parameter. type must be one of OLGX_UPPER_LEFT, 
OLG X_LOWER_LEFT, OLGX_UPPER_RIGHT, or OLGX_LOWER_RIGHT. state 
must be either OLGX_NORMAL or OLGX_INVOKED.



void
olgx_draw_pushpin(ginfo, win, x, y, state)

	Graphics_info *ginfo;
	Window win;
	int x, y, state;

This function renders a pushpin at the requested location. (x, y) and win specify the loca-
tion and window of the resize corner, respectively. The state of the pushpin is determined 
by the state parameter. state must be a bitwise or combination of the following:

OLGX_PUSHPIN_OUT 	The pushpin is out.

OLGX_PUSHPIN_IN 	The pushpin is in.

OLGX_ERASE 	The area behind the pushpin will be erased before the pushpin 
is drawn. This flag allows the new pushpin to erase the previ-
ous one when it changes states.

OLGX_INACTIVE 	Pushpin is inactive; it will be drawn with a 50% grey stipple.

OLGX_DEFAULT 	The pushpin is a default pushpin.



void
olgx_draw_box(ginfo, win, x, y, width, height, state, fill_in)

	Graphics_info *ginfo;
	Window win;
	int x, y, width, height, state, fill_in;

olgx_draw_box() draws a beveled box of the given size at the specified location. state de-
scribes the state of the box. It may be either OLGX_NORMAL or OL GX_INVOKED. In 
3D mode, an invoked box is drawn as a recessed rectangle and a normal box is drawn as a 
raised rectangle. If fill_in is nonzero, then the box is filled in. The state flag can take 
OLGX_ERASE to erase the underlying box before drawing over it.

void 
olgx_draw_choice_item(ginfo, win, x, y, width, height, label, state) 

	Graphics_info *ginfo;

	Window win;

	int x, y, width, height;

	long label;

	int state;

olgx_draw_choice_item() will render a choice item with either a pixmap or character 
string label. win designates what window the item is to be drawn in. x and y give the coor-
dinates of the upper-left corner of the choice item, and width and height denote its outside 
width and height.   The label of a choice item can either be a character string or an X pix-
map. If the label is a character string, label is a pointer to a character. If the label is an X 
pixmap, label is a pointer to the struct Pixlabel. The struct Pixlabel is explained below and 
is to be initialized appropriately. If the given label is too large to fit in the button, it will be 
clipped appropriately. Finally, state gives the current state of the item. It consists of a bit-
wise-OR of any of the following flags:

OLGX_NORMAL 	The item is not invoked. In a "3D" environment, it will 
be drawn as a raised rectangle.

OLGX_INVOKED 	The item is invoked. In a "3D" environment, it will be 
drawn as a recessed rectangle.

OLGX_DEFAULT 	This is a default choice item. An inner default rectangle 
will be drawn to denote it as such.

OLGX_INACTIVE 	This item is inactive. It will be drawn with a 50% grey 
stipple.

OLGX_LABEL_IS_PIXMAP 	The label specified is an X Pixmap ID. If this flag is not 
given, olgx_draw_choice_item will assume that the la-
bel is a character string.

	Struct Pixlabel {
		XID	pixmap;
		int	width;	/* width of the pixmap */
		int	height;	/* height of the pixmap */
	}

Note: If the label is a pixmap, the width of the choice item is always incremented by 
OLGX_CHOICE_MARGIN which accommodates the space for a default ring 
around the pixmap in case OLGX_DEFAULT is set.



void
olgx_draw_check_box(ginfo, win, x, y, state)

	Graphics_info *ginfo;
	Window win;
	int x, y, state;

olgx_draw_check_box() renders a check box in a specified state. The upper left-hand cor-
ner of the check box will be at location (x, y) within window win. state must be one of the 
following:

OLGX_NORMAL 	The check box is unchecked.

OLGX_INVOKED 	The check box is recessed. OPEN LOOK specifies that this is 
the state of the check box while the mouse button is down 
over the check box.

OLGX_INACTIVE	The check box is drawn in inactive state.

OLGX_CHECKED 	The check box is checked.



void
olgx_draw_scrollbar(ginfo,win,x,y,length,elev_pos,old_elev_pos,prop_pos,prop_length, 
state)

	Graphics_info * ginfo;
	Window win;
	int x,y;
	int length;
	int elev_pos, old_elev_pos;
	int prop_pos, prop_length;
	int state;

olgx_draw_scrollbar() renders or updates a whole scrollbar, including the elevator, cable 
and proportion indicator. win, x, y, elev_pos, length, prop_pos, prop_length are shown in 
the following figure. 

old_elev_pos is the previous position of the elevator when it is in motion. This is used 
only when the flag OLGX_UPDATE is set.

Finally state can have any of the following flags bitwise-ORed.

OLGX_VERTICAL	The elevator is vertical.

OLGX_HORIZONTAL 	The elevator is horizontal.

OLGX_NORMAL	The elevator is normal.

OLGX_ABBREV	Abbreviated scrollbar elevator

OLGX_SCROLL_ABSOLUTE 	The elevator middle box is drawn in invoked 
fashion.

OLGX_SCROLL_BACKWARD 	The elevator backward box is invoked to indi-
cate that the elevator is moving backwards.

OLGX_SCROLL_FORWARD 	The elevator forward box is invoked to indicate 
that the elevator is moving forwards.

OLGX_SCROLL_NO_BACKWARD	The elevator backward box is dimmed, to indi-
cate that the elevator cannot move backward 
anymore.

OLGX_SCROLL_NO_FORWARD 	The elevator forward box is dimmed, to indicate 
that the elevator cannot move forward anymore.

OLGX_INACTIVE	The whole elevator is drawn dimmed, indicating 
that the elevator is inactive.

OLGX_UPDATE	Update the scrollbar elevator to its new location. 
If OLGX_UPDATE is not specified the parame-
ters old_elev_pos will not be used.

OLGX_ERASE	Erases the underlying image before drawing the 
elevator at location elev_pos.

Use olgx_draw_box for drawing the end anchors.



void
olgx_draw_text_ledge(ginfo, win, x, y, width)

	Graphics_info *ginfo;
	Window win;
	int x, y, width;

This function draws a 2D or 3D ledge for text items. The ledge is drawn with its left edge 
at (x,y) within win, and width pixels wide.



void
olgx_draw_text(ginfo,win,string,x,y,max_width,state)

	Graphics_info * ginfo;
	Window win;
	char * string;
	int x,y;
	int max_width;
	int state;

This function renders string in win at x,y. max_width defines, in pixels, the point at which 
string will be truncated. That is, if the length of string exceeds max_width, it will be trun-
cated. If max_width is 0, the string will not be truncated. By default it is drawn in the nor-
mal uninvoked mode. Finally state is a bitwise-OR of any of the following flags.

OLGX_INVOKED	In 2-D, text will appear in reverse video:

OLGX_NORMAL	In 2-D, text will appear in normal video. 3-D, whether normal or 
invoked, will always appear in normal video.



olgx_draw_textscroll_button(ginfo,win,x,y,state)

	Graphics_info * ginfo;
	Window win;
	int x,y;
	int state;

olgx_draw_textscroll_button() renders a text scrolling button. It is drawn within window 
win at location x,y. By default it is drawn in the normal uninvoked mode. Finally state is a 
bitwise-OR of any of the following flags.

OLGX_ERASE	Erases the underlying image before drawing the but-
ton at location x,y.

OLGX_INVOKED	Will be drawn in Invoked state.

OLGX_SCROLL_FORWARD	Will drawn with the inside menu mark pointing for-
wards.

OLGX_SCROLL_BACKWARD	Will be drawn with the inside menu mark pointing 
backwards. 

OLGX_INACTIVE	The button is inactive. It will be drawn dimmed.



olgx_draw_numscroll_button(ginfo,win,x,y,state)

	Graphics_info * ginfo;
	Window win;
	int x,y;
	int state;

olgx_draw_numscroll_button() renders a numeric scrolling button. It is drawn within 
window win at location x,y. By default it is drawn in the normal uninvoked mode. Finally 
state is a bitwise-OR of any of the following flags.

OLGX_ERASE	Erases the underlying image before drawing the 
button at location x,y.

OLGX_SCROLL_FORWARD	Will be drawn with the right box invoked 					indicat-
ing to the user that he is scrolling forward

OLGX_SCROLL_BACKWARD 	Will be drawn with the left box invoked 					indicating 
to the user that he is scrolling back.

OLGX_SCROLL_NO_FORWARD 	Will be drawn with the forward menu mark box 
dimmed.

OLGX_SCROLL_NO_BACKWARD 	Will be drawn with the backward menu mark box 
dimmed.

OLGX_INACTIVE	The button is inactive. It will be drawn dimmed.



olgx_draw_gauge(ginfo,win,x,y,width,oldval,newval,state)

	Graphics_info * ginfo;
	Window win;
	int x,y;
	int width;
	int newval,oldval;
	int state;

olgx_draw_gauge() renders a gauge. It is drawn within window win at location x,y. width 
represents the width of the gauge in pixels, including the endcaps. oldval and newval give 
the old and new values of the gauge in pixels with the origin at either the top (vertical 
gauges) or the left (horizontal gauges) of the gauge. Finally, state gives information about 
the current state of the gauge. It consists of the bitwise-OR of any of the following flags:

OLGX_VERTICAL	Vertical gauge

OLGX_HORIZONTAL	Horizontal gauge

OLGX_UPDATE	Update the gauge to newval instead rendering the whole gauge.

If OLGX_UPDATE is not specified, the parameter oldval will not be used. 

5.0  OLGX MACROS:

The following macros are provided for convenience and because the ginfo struct is intend-
ed to be opaque; clients shouldn't access its members directly. The reason for it being 
opaque is that OLGX's authors want to retain the option to change the members in the 
ginfo struct without making existing clients obsolete.

Abbrev_MenuButton_Height(ginfo) returns the height of the abbreviated MenuButton 
from the specified ginfo struct.

Abbrev_MenuButton_Width(ginfo) returns the width of the abbreviated MenuButton 
from the specified ginfo struct.

Ascent_of_GlyphFont(ginfo) returns the ascent of the glyph font associated with the spec-
ified ginfo struct.

Ascent_of_TextFont(ginfo) returns the ascent of the text font associated with the specified 
ginfo struct.

Button_Height(ginfo) returns the height of the button from the specified ginfo struct.

ButtonEndcap_Width(ginfo) returns the width of the button endcap from the specified 	
ginfo struct.

CheckBox_Height(ginfo) returns the height of the checkbox from the specified ginfo 
struct.

CheckBox_Width(ginfo) returns the width of the checkbox from the specified ginfo struct.

Dimension(ginfo) returns 1, if 3D is set in the specified ginfo struct, else returns 0.

Descent_of_GlyphFont(ginfo) returns the descent of the glyph font associated with the 
specified ginfo struct.

Descent_of_TextFont(ginfo) returns the descent of the text font associated with the speci-
fied ginfo struct.

Gauge_EndCapHeight(ginfo) returns the height of the gauge endcap from the specified 
ginfo struct.

Gauge_EndCapOffset(ginfo) returns the pixel offset of the value indicator from the left or 
top endcap of the gauge from the specified ginfo struct.

Gauge_EndCapWidth(ginfo) returns the width of the gauge endcap from the specified gin-
fo struct.

HorizSliderControl_Width(ginfo returns the width of the Horizontal slider control section 
of the ginfo struct. This corresponds to the Vertical Slider Control Height.

HorizSliderControl_Height(ginfo) returns the height of the Horizontal slider control sec-
tion of the specified ginfo struct. This corresponds to the Vertical slider control Width.

MenuMark_Height(ginfo) returns the height of the MenuMark used in MenuButtons from 
the specified ginfo struct.

MenuMark_Width(ginfo) returns the width of the MenuMark used in MenuButtons from 
the specified ginfo struct.

NumScrollButton_Height(ginfo) returns the height of the Number scrolling button from 
the specified ginfo struct.

NumScrollButton_Width(ginfo) returns the width of the Number scrolling button from 
the specified ginfo struct.

Pointsize_Glyph(ginfo) returns the point size of the glyph font associated with the speci-
fied ginfo struct.

PushPinOut_Height(ginfo) returns the height of the PushPin in its Out state from the 
specified ginfo struct.

PushPinOut_Width(ginfo) returns the width of the PushPin in its Out state from the spec-
ified ginfo struct.

ResizeArm_Height(ginfo) returns the height of the resize arm from the specified ginfo 
struct (see figure).

ResizeArm_Width(ginfo) returns the width of the resize arm from the specified ginfo struct 
(see figure).

ScrollbarElevator_Height(ginfo) returns the scrollbar elevator height from the specified 
ginfo struct.

ScrollbarElevator_Width(ginfo) returns the scrollbar elevator width from the specified 
ginfo struct.

SliderEndCap_Width(ginfo) returns the width of the slider endcap of the specified ginfo 
struct. Both vertical and horizontal sliders have the same endcap width.

SliderEndCap_Height(ginfo) returns the height of the slider endcap from the specified 
ginfo struct. Both vertical and horizontal sliders have the same endcap height.

TextFont_Struct(ginfo) returns the XFontstruct of the text font from the specified ginfo 
struct.

TextScrollButton_Height(ginfo) returns the height of the Text scrolling button from the 
specified ginfo struct.

TextScrollButton_Width(ginfo) returns the width of the Text scrolling button from the 
specified ginfo struct.

Vertsb_Endbox_Height(ginfo) returns the height of the end anchor box of a vertical scroll-
bar from the specified ginfo struct.

Vertsb_Endbox_Width(ginfo) returns the width of the end anchor box of a vertical scroll-
bar from the specified ginfo struct.