[Home] [ToC] [Up] [Prev] [Next]
The browser's user interface services provide types and routines for creating and manipulating graphical user interfaces. They are typically implemented as part of the operating system glue, abstracting its native GUI system.
void* (This is an opaque
type that is defined by the browser's internal
implementation.)
This type represents a single color that can be used to draw in.
void* (This is an opaque
type that is defined by the browser's internal
implementation.)
This type represents a font that can be used to render text.
void* (This is an opaque
type that is defined by the browser's internal
implementation.)
This type represents a single color that can be used to draw in.
typedef int (*IHFutureCallback)
IH_PROTO((IHGlobalInfo* gi,IHDocument doc,void* userdata));
(IHGlobalInfo*)
gi
(IHDocument)
doc
(void*)
userdata
This is the prototype of the function that is called when an IHFutureCall occurs. The function can do whatever it needs to service the future call, then returns; once it returns, the IHFutureCall object is automatically deallocated. This callback should always return zero.
typedef struct ih_member_value_rec {
IHWidgetMember member;
void* value;
} IHMemberValue;
This is used to associated widget members with their associated values, for retrieving and setting them.
void* (This is an opaque
type that is defined by the browser's internal
implementation.)
This type represents the context needed to perform drawing operations. It can actually be one of two forms, both of which look identical: either an off-screen display buffer that can be drawn into, or a handle on a IHWidgetRep object's on-screen display context.
In either case, it encapsulates all of the display context needed for drawing, including the current font, pen, and clipping region.
typedef enum {
IWM_NULL_ID = 0, /* Nothing */
IWM_IGNORE_ID, /* A do-nothing value */
IWM_INTERFACE_ID, /* (IHGlobalInfo*) iHTML context */
IWM_DOCUMENT_ID, /* (IHDocument) Browser doc widget is on */
IWM_LANGENV_ID, /* (IHLangInfo*) language associate with */
IWM_CODEINFO_ID, /* (IHCodeInfo*) code owning, or NULL */
IWM_PARENT_ID, /* (IHWidgetRep) The widget's parent */
IWM_NAME_ID, /* (const char*) The name of the widget */
IWM_WIDGETREP_ID, /* (IHWidgetRep) The browser-side widget */
IWM_WIDGETOBJ_ID, /* (IHWidgetObj) The language-side object */
IWM_WIDGETRAW_ID, /* (IHWidgetRaw) browser/OS impl object */
IWM_VISIBLE_ID, /* (int) Visible? TRUE/FALSE */
IWM_X_ID, /* (int) Absolute X position */
IWM_Y_ID, /* (int) Absolute Y position */
IWM_WIDTH_ID, /* (int) Absolute width */
IWM_HEIGHT_ID, /* (int) Absolute height */
IWM_BACKGROUNDFILL_ID, /* (IHColor) Current background color */
IWM_BACKGROUNDPIXMAP_ID, /* (IHColor) Current background pixmap */
IWM_FOREPEN_ID, /* (IHColor) Current foreground pen */
IWM_BACKPEN_ID, /* (IHColor) Current foreground pen */
IWM_FONT_ID, /* (IHFont) Current text font */
IWM_PIXMAP_ID, /* (IHPixmap) Where to draw on widget */
IWM_MOUSEX_ID, /* (int) Current Mouse X position */
IWM_MOUSEY_ID, /* (int) Current Mouse Y position */
IWM_MOUSESTATE_ID, /* (int) Current Mouse state flags */
IWM_KEYSTATE_ID, /* (int) Current keyboard state flags */
_IWM_NUM
} IHWidgetMember;
This type is an enumeration of the attributes that are associated with IHWidgetRep and IHPixmap objects.
void* (This is an opaque
type that is defined by the browser's internal
implementation.)
This type is a handle on the OS object that the browser is actually using to implement its widget. Under X, this is either a Widget or Window object. It is used by language modules that wish to directly access the operating system for managing their user interface.
void* (This is an opaque
type that is defined by the browser's internal
implementation.)
This type represents a browser-side user interface object. This object defines a window on the screen with its own display context, provides functions for drawing in it, and sends events about user interaction with it. It does not generally, however, provide any high-level intellegence about how to respond to these events -- instead, that is implemented by the language-side IHWidgetObj.
As an example, under X this type would be implemented as either a low-level X window or a simple Xt widget that blindly collects events and sends them to its associated language-side object.
IHFutureCall
BR_AddFutureCall(IHGlobalInfo*
gi, IHDocument doc, int sec, int micro, IHFutureCallback
func, void* userdata)
(IHGlobalInfo*)
gi
(IHDocument)
doc
(int)
sec
(int)
micro
(IHFutureCallback)
func
(void*)
userdata
(IHFutureCall) A premonition
of things to come.
Constructs the context on a function call that is to be performed at some future time. The system will try to make the call as accurately as possible, but it makes no guarantees -- in particular it will not be made until control returns to the browser.
IHColor BR_AllocIHColor(IHWidgetRep
widget, unsigned short red, unsigned short green, unsigned
short blue)
(IHWidget)
widget
(unsigned short)
red
(unsigned short)
green
(unsigned short)
blue
(IHColor) A new drawing pen
color.
Allocates a new pen drawing color, that can then be used in calls such as BR_PixSetForePen() and setting an IHWidgetRep's IWM_BACKGROUNDPEN_ID member.
The returned color is as close to the desired color indicated by the arguments -- this accuracy is constrained by such things as the host system's color bit depth, type of display (e.g., monochrome or color), and the availability of colors in the display's palette.
The indicated color brightness levels range from zero (black) to MAX_COLOR (brightest), where MAX_COLOR is 0xFFFF.
IHPixmap BR_AllocIHPixmap(IHWidgetRep
widget, int width, int height)
(IHWidget)
widget
(int)
width
(int)
height
(IHPixmap) A newly created
off-screen pixmap.
Allocates a new off-screen display buffer, in the given widget context. Standard drawing operations may then be performed in this context. Each IHPixmap tracks its own drawing pens, text font, and clipping region; off-screen pixmaps allocated with this function also have their own block of memory in which they are drawn.
As with widget members, the IHPixmap always owns the member values that it starts out with, and deallocates those when it is deallocated. Any values a program allocates and sets for the pixmap are only being lent to it -- the pixmap will never free them, and the program must be sure to deallocated them after the pixmap is destroyed or no longer has that value set in any of its attributes.
IHWidgetRep BR_AllocWidget(IHGlobalInfo*
gi, IHDocument doc, IHWidgetRep par,
IHWidgetObj obj, const IHMemberValue* init)
(IHGlobalInfo*)
gi
(IHDocument)
doc
(IHWidgetRep)
par
(IHWidgetObj)
obj
(const IHMemberValue*)
init
(IHWidgetRep) The newly
created browser-side widget.
Creates a new browser widget with the given member values. The argument par is the widget's structural parent; if NULL, the widget is a parent of the entire document. The widget's members are initialized to the IWM_NULL_ID terminated array of member values. Its default values are:
The argument obj may be NULL, in which case the back-end language object can be attached to the widget later. This usually occurs when the top-level widget of an object is created -- the browser widget is first created, and returned to the browser. Once the language code has been retrieved from the network, the language object is then attached to the previously created browser widget by setting its IWM_WIDGETOBJ_ID attribute.
Note on widget members: the ownership of member values is very strictly defined. Any values (e.g., IHFont or IHColor objects) an IHWidgetRep allocates itself are automatically deallocated by the widget when it is destroyed, whether or not they are currently set in the widget. Any values a program allocates and sets for the widget are only being lent to it -- the widget will never free them, and the program must be sure to deallocated them after the widget is destroyed or no longer has that value set in any of its attributes.
This applies even for member values that are supplied by the program when it first creates a widget: the program still owns these values, and must appropriate deallocate them when done with them.
void BR_FlushDisplay(IHWidgetRep
widget)
(IHWidgetRep)
widget
Flushes all drawing operations in the display that contains widget, so that it is up-to-date with what the program has done.
void BR_FreeIHColor(IHColor
color)
(IHColor)
color
Deallocate an IHColor that was previously allocated with BR_AllocIHColor(). A color should not be deallocated until it no longer appears in the IHPixmap images it was used in.
void BR_FreeIHPixmap(IHPixmap
pixmap)
(IHPixmap)
pixmap
Deallocate an IHPixmap that was previously allocated with BR_AllocIHPixmap(). Any attributes created by the pixmap (e.g., its default IHFont and foreground pen) are also deallocated, whether or not they are currently set in the pixmap.
void BR_FreeWidget(IHWidgetRep
widget)
(IHWidgetRep)
widget
Deallocate and destroyed a previously allocated browser-side widget, along with all of its children. Any attributes created along with the widget (e.g., its default IHFont and foreground pen) are also deallocated, whether or not they are currently set in the widget.
void BR_GetPixmapMembers(IHPixmap
pixmap, IHMemberValue* values)
(IHPixmap)
pixmap
(const IHMemberValue*)
value
/* Get a pixmap's dimensions and drawing state. */
{
IHMemberValue val[5] = {
{ IWM_WIDTH_ID, 0 },
{ IWM_HEIGHT_ID, 0 },
{ IWM_FOREPEN_ID, 0 },
{ IWM_FONT_ID, 0 },
{ IWM_NULL_ID, 0 }
};
int w=0, h=0;
IHColor pen;
IHFont font;
val[0].value = &w;
val[1].value = &h;
val[2].value = &pen;
val[3].value = &font;
BR_GetPixmapMembers(widget,&val[0]);
}
Retrieves the values of pixmap member attributes. The argument values is an array of IHMemberValue structures, terminated with a member of IWM_NULL_ID. Each value field points to a variable that will be filled in with the associated member's current value.
void BR_GetWidgetMembers(IHWidgetRep
widget, IHMemberValue* values)
(IHWidgetRep)
widget
(const IHMemberValue*)
value
/* Get a widget's position and dimensions. */
{
IHMemberValue val[5] = {
{ IWM_X_ID, 0 },
{ IWM_Y_ID, 0 },
{ IWM_WIDTH_ID, 0 },
{ IWM_HEIGHT_ID, 0 },
{ IWM_NULL_ID, 0 }
};
int x=0, y=0, w=0, h=0;
val[0].value = &x;
val[1].value = &y;
val[2].value = &w;
val[3].value = &h;
BR_GetWidgetMembers(widget,&val[0]);
}
Retrieves the values of widget member attributes. The argument values is an array of IHMemberValue structures, terminated with a member of IWM_NULL_ID. Each value field points to a variable that will be filled in with the associated member's current value.
void BR_PixBltPixmap(IHPixmap
dest, int x, int y, IHPixmap src, int xsrc, int ysrc,
int w, int h)
(IHPixmap)
dest
(int)
x
(int)
y
(IHPixmap)
src
(int)
xsrc
(int)
ysrc
(int)
w
(int)
h
Performs a bit-blit operation from src into the dest pixmap. Either the entire dest pixmap is copied, or any sub-rectangle can be copied, whose top-left corner is (xsrc,ysrc) and dimensions are (w x h).
void BR_PixClearRectangle(IHPixmap
pixmap, int x, int y, int w, int h)
(IHPixmap)
pixmap
(int)
x
(int)
y
(int)
w
(int)
h
Clears the rectangle region in the pixmap, whose top-left pixel is at (x,y) and that is w pixels wide and h pixels high. If w or h are zero, no rectangle is cleared. The rectangle is cleared to the IHPixmap's current IWM_BACKGROUNDPEN_ID or IWM_BACKGROUNDPIXMAP_ID.
void BR_PixDrawArc(IHPixmap pixmap, int
x, int y, int w, int h, float a1, float a2)
(IHPixmap)
pixmap
(int)
x
(int)
y
(int)
w
(int)
h
(float)
a1
(float)
a2
Draws an unfilled arc in pixmap, whose farthest left pixel is at x, farthest top pixel is at y, and that is w pixels wide and h pixels high, using the current IWM_FOREPEN_ID color. The arc starts at the a1 degree position, and extends to the a2 degree position. If w or h are zero, no arc is drawn. A complete oval is drawn by setting a1 to 0.0 and a2 to 360.0.
void BR_PixDrawLine(IHPixmap
pixmap, int x1, int y1, int x2, int y2)
(IHPixmap)
pixmap
(int)
x1
(int)
y1
(int)
x2
(int)
y2
Draws a line in the pixmap, going from (x1,y1) to (x2,y2). The line is drawn in the IHPixmap's current IWM_FOREPEN_ID color.
void BR_PixDrawRectangle(IHPixmap
pixmap, int x, int y, int w, int h)
(IHPixmap)
pixmap
(int)
x
(int)
y
(int)
w
(int)
h
Draws an unfilled rectangle in the pixmap, whose top-left pixel is at (x,y) and that is w pixels wide and h pixels high. If w or h are zero, no rectangle is drawn. The rectangle is drawn in the IHPixmap's current IWM_FOREPEN_ID color.
void BR_PixDrawText(IHPixmap pixmap,
IHFont font, int length, const char* text, int x, int
baseline, int justify)
(IHPixmap)
pixmap
(IHFont)
font
(int)
length
(const char*)
text
(int)
x
(int)
baseline
(int)
justify
Draws the given text string into the IHPixmap, rendering it with the given font, in the IHPixmap's current foreground pen. Its base line is vertically located at the argument baseline, and x and justify are used to determine the horizontal location as follows:
All other values for justify are invalid, and should not be used.
void BR_PixFillArc(IHPixmap pixmap, int
x, int y, int w, int h, float a1, float a2)
(IHPixmap)
pixmap
(int)
x
(int)
y
(int)
w
(int)
h
(float)
a1
(float)
a2
Draws an filled arc in pixmap, whose farthest left pixel is at x, farthest top pixel is at y, and that is w pixels wide and h pixels high, using the current IWM_FOREPEN_ID color. The arc starts at the a1 degree position, and extends to the a2 degree position. If w or h are zero, no arc is drawn. A complete oval is drawn by setting a1 to 0.0 and a2 to 360.0.
void BR_PixFillRectangle(IHPixmap
pixmap, int x, int y, int w, int h)
(IHPixmap)
pixmap
(int)
x
(int)
y
(int)
w
(int)
h
Draws an filled rectangle in the pixmap, whose top-left pixel is at (x,y) and that is w pixels wide and h pixels high. If w or h are zero, no rectangle is drawn. The rectangle is drawn in the IHPixmap's current IWM_FOREPEN_ID color.
void BR_PixSetBackPen(IHPixmap pixmap,
IHColor color)
(IHPixmap)
pixmap
(IHColor)
color
Sets the current active background rendering pen for the given IHPixmap display context. This is a short-hand for calling BR_SetPixmapMembers() to set its IWM_BACKPEN_ID member.
void BR_PixSetFont(IHPixmap pixmap,
IHFont font)
(IHPixmap)
pixmap
(IHFont)
font
Sets the current active text rendering font for the given IHPixmap display context. This is a short-hand for calling BR_SetPixmapMembers() to set its IWM_FONT_ID member.
void BR_PixSetForePen(IHPixmap pixmap,
IHColor color)
(IHPixmap)
pixmap
(IHColor)
color
Sets the current active foreground rendering pen for the given IHPixmap display context. This is a short-hand for calling BR_SetPixmapMembers() to set its IWM_FOREPEN_ID member.
void BR_PixTextExtent(IHPixmap pixmap,
IHFont font, int length, const char* text, int* ascent,
int* descent, int* width)
(IHPixmap)
pixmap
(IHFont)
font
(int)
length
(const char*)
text
(int*)
ascent
(int*)
descent
(int*)
width
Computes the metrics if the given string of text had been rendered in the given font.
void BR_RemFutureCall(IHFutureCall
call)
(IHFutureCall)
call
Aborts a future call that was initiated with BR_AddFutureCall(). This function must be called before the call occurs -- afterwards, the IHFutureCall object is invalid. It also can not be called inside of the future call's IHFutureCallback function.
void BR_SetPixmapMembers(IHPixmap
pixmap, IHMemberValue* values)
(IHPixmap)
pixmap
(const IHMemberValue*)
value
Sets the values of a pixmap's member attributes. The argument values is an array of IHMemberValue structures, terminated with a member of IWM_NULL_ID.
void BR_SetWidgetMembers(IHWidgetRep
widget, IHMemberValue* values)
(IHWidgetRep)
widget
(const IHMemberValue*)
value
Sets the values of a widget's member attributes. The argument values is an array of IHMemberValue structures, terminated with a member of IWM_NULL_ID.
[Home] [ToC] [Up] [Prev] [Next]
| Dianne Kyra Hackborn <hackbod@angryredplanet.com> | Last modified: Tue Oct 8 03:59:15 PDT 1996 |