MPDWIN(3)

NAME
mpdwin - X-Windows graphics interface for MPD

SYNOPSIS
(in MPD program:)import MPDWin
(to build:)mpd program.mpd mpdwin.o -lX11
(with mpdm:)mpdm program.mpd mpdwin.o -lX11

DESCRIPTION
MPDWin provides a set of window interface operations to the MPD programmer. It is based on the Xlib interface to the X window system. The application imports a global MPDWin and links with a file of associated C functions and the X library. The library is often found simply by linking -lX11, but some systems may require a different specification. The package supports five basic types of objects: windows, events, fonts, cursors, and images. Windows are primary objects for input and output. Cursors and fonts are resources of the underlying X Window System, which define the visible shape of the pointing device and the appearance of textual output respectively. Window events are queued in the order of their occurrence and handled later either by the MPDWin package or by the application program.

Windows
    Windows can be displayed on a X server or they can be off-screen pixmaps. To the programmer they are obscured data structures. They reside in the X server's memory, which means drawings on windows must be packed as requests and sent to the X server (probably through the network). A window cannot be shared among processes on different virtual machines. A backup copy of each window's contents is maintained in the package for automatic refreshing when needed. A window can be treated as an abstract drawing surface without regard to overlap or visibility considerations. Usually a graphics primitive does not contain all the information needed to draw a particular thing. The X server maintains resources called graphics contexts (GCs) that specify many attributes that apply to each graphic request. GCs reduce the traffic between the X server and the application programs (clients of the X server) in two ways. First, the GC information is maintained by the X server and only needs to be sent once, and later drawing requests use the id of the GC to draw. In the case of changes, only the selected few fields need to be sent. Second, multiple GCs can be created so clients can switch among different graphic bindings with ease. MPDWin treats GCs as parts of a window. The application program creates a new GC binding by calling WinNewContext() to get a new window structure with the new GC, while it still refers to the old window. A window can have many subwindows as its children. All children are displayed on top of their parents when mapped (which means ``ready for display''). When the extent of a window intersects with that of a sibling window, these two windows can be displayed in any order. MPDWin provides a few primitives for managing subwindows.

Events
    All inputs from a window are modeled as events. Events that require a part of the screen to be redrawn are handled automatically by the MPDWin package. Other events can be processed by the application program. Unlike most other X Window packages, with which application programs play a passive role responding to events, MPDWin lets an application program manage the control flow directly. To receive events on a window, the application program selects events of interest by specifying an event mask. When an event occurs, it is checked with the window's mask; if the particular event not selected, it is propagated to the parent window, and so on, until it reaches a window for which the event is selected or ignored (in which case the event is discarded).

Images
    Images are rectangular areas of pixels; unlike windows, they reside on the client instead of the server, and they are always invisible. Images support only a limited set of operations, but image modification operations can be accomplished very quickly because they require no communication with the server. The typical use is to constuct an image locally, possibly a pixel at a time, and then copy it to the screen as a unit.

Fonts and Cursors
    A cursor is a transient shape that moves on the screen as the mouse moves on its pad to indicate where the mouse is pointing. Different windows may have different cursor shapes. A font is a set of bitmaps representing characters, cursor shapes, or other small patterns. In MPDWin, fonts and cursors come from a predefined set supported by the underlying X Window System.

OUTPUT MODEL

All window output operations are defined in terms of an integer coordinate system with its origin at the top-left corner of the window.

Lines, ellipses, texts, and individual pixels can be drawn. Multiple characteristics of drawing and filling can be controlled. These include line width, line style, cap style, join style, dashes and dash offset, fill style and fill rule.

To further reduce the communication traffic between the X server and the application program, drawing can be temporarily disabled (on a per top-level window basis). Then the client must explicitly tell the X server to update the window contents. Alternatively the application can choose to construct an image and send the image as a whole to the X server for display.

INPUT MODEL

All input accepted by the package is represented by a uniform event record data structure, which includes information about:
    • type of the event
    • window in which the event occurred
    • coordinates of the pointer within the window when the event occurred
    • the status of the mouse buttons (up or down)
    • the status of the SHIFT, CONTROL, and META keys
    • specific values associated with the particular event type (e.g. button number when it is a button press or release event; ASCII code of keypress; etc.)

Each event from a window is dispatched to the event-message channel of that window. This channel is provided by the user program when it calls MPDWin to create a window. If the user program doesn't provide an event channel, the window can be used only for output.

The user program can determine whether there is event pending by checking the number of messages in the event channel, or it can wait on the event channel until an event happens. The application can specify the event types of interest and have all other events discarded automatically. A process is generated for each window to poll for events.

EVENT CHANNEL

The MPDWin global exports
    optype winEventChannel(winEvent) {send}
The application program can use this optype to declare a message channel.

When a selected event occurs, MPDWin sends a winEvent record to the registered input channel for the window. The winEvent record contains the following fields:

event_type
    Type of the event.

window
    The window in which the event occurred.

x, y
    Coordinates of the pointer within the window when the event occurred.

bk_status
    Inclusive OR of flags indicating the currently pressed buttons and keys:
    	BK_None	BK_Button1	BK_Mod1
    	BK_CNTRL	BK_Button2	BK_Mod2
    	BK_LOCK	BK_Button3	BK_Mod3
    	BK_SHIFT	BK_Button4	BK_Mod4
    		BK_Button5	BK_Mod5

data
    For a key event, data specifies which key or button was pressed or released, and it can be converted to the corresponding character. For a mouse button event, data is one of the button masks listed above. For a enter/leave window event, data can be converted to a boolean value indicating whether the window has the focus or not. For all other events, this field is undefined.

keysym
    Numerical value of standard X KeySym as defined in C header file <X11/keysymdef.h> and the KeySym database /usr/lib/X11/XKeysymDB. It is useful for detecting keys that do not have corresponding ASCII character representations, such as function keys and arrow keys.

OTHER DATA STRUCTURES

winWindow
    Pointer to a record structure that holds all information for a window.

winInitialState
    Integer value specifying the initial state of an object when creating it.

winError
    Integer value that is zero in the case of an error or nonzero if successful.

winStdCursor
    An enumeration of the set of defined cursor shapes.

winCursor
    Pointer representing the handle of a cursor.

winColor
    String containing a color name or a numerical color specification.

winPixel
    Pointer representing the handle of a colormap entry.

winFont
    Pointer to a structure that holds information for a loaded font.

winImage
    Pointer to an image structure.

winPoint
    Record of (x, y) coordinates.

winRectangle
    Record of (x, y, w, h) for the coordinates of the top-left corner of the rectangle and its width and height.

winLineStyle
    Enumeration of valid line styles: LineSolid, LineDoubleDash, LineOnOffDash

winCapStyle
    Enumeration of valid cap styles: CapNotLast, CapButt, CapRound, CapProjecting

winJoinStyle
    Enumeration of valid join styles: JoinMiter, JoinRound, JoinBevel

winFillStyle
    Enumeration of valid fill styles: FillSolid, FillTiled, FillOpaqueStippled, FillStippled

winFillRule
    Enumeration of valid fill rules: FillEvenOddRule, FillWindingRule

winArcMode
    Enumeration of valid arc modes: ArcChord, ArcPieSlice

winDrawOp
    Enumeration of valid drawing operations: these control how the source pixel values generated by a graphics request are combined with the old destination pixel values already on the screen to produce the final destination pixel values. The operations are:
    Op_Clear	Op_And
    Op_AndReverse	Op_Copy
    Op_AndInverted	Op_Noop
    Op_Xor	Op_Or
    Op_Nor	Op_Equiv
    Op_Invert	Op_OrReverse
    Op_CopyInverted	Op_OrInverted
    Op_Nand	Op_Set

NAMING AND ARGUMENT CONVENTIONS

MPDWin follows a set of conventions for the naming and syntax of the functions:
    • The names of all MPDWin functions begin with Win followed by compound words which are constructed by capitalizing the first letter of each word.
    • Names of user-visible data structures and types begin with win. Names of all members of data structures use lower case.
    • The window argument, where used, is always first in the argument list. The image argument, where used, is always right after the window argument when there is one, or the first when there is no window argument.
    • Source arguments always precede destination arguments in an argument list.
    • An x argument always precedes a y argument in an argument list.
    • A width argument always precedes a height argument in an argument list.
    • If x, y, width, and height arguments are used together, the x and y arguments always precede the width and height arguments.
    • If a procedure returns an integer, a value of zero serves as an error indicator. If a procedure returns a pointer, null indicates an error. Not all errors are reported in this manner; some (especially those that cannot be detected immediately) abort the program.

FUNCTIONS
General Functions

WinOpen (display: string[*]; title: string[*]; evchannel: cap winEventChannel; state: winInitialState; w, h: int) returns win: winWindow
WinCreateSubwindow (oldwin: winWindow; evchannel: cap winEventChannel; state: winInitialState; x, y, w, h: int) returns newwin: winWindow WinOpen() opens and initializes a top-level window of width w pixels, height h pixels, and with the same depth of the root window, with white foreground and black background. If WinOpen() can't open such a window, a null pointer is returned. WinCreateSubwindow() creates a subwindow as oldwin's child. The subwindow begins at (x, y) relative to its parent's top-left corner. The initialization includes opening a connection to the X server, creating a window, creating a backing store, allocating a graphics context and a colormap, loading default font, setting default window attributes, etc. If the display argument is a null string, MPDWin then tries to open that window on the screen specified by the environment variable DISPLAY. When state equals to UseDefault, the created window is displayed on screen (at a position determined by the window manager for the top-level window case), and output to the window is enabled. If state equals to OffScreen, the window is off screen and can be made visible by calling WinMapWindow(), while direct output is initially disabled. The evchannel argument is used to register a message channel to receive incoming window events. It can be null if no event reporting is wanted. If the window is on screen at the beginning and evchannel is not null, then all events are selected on this window. For a subwindow, the graphics context information is inherited from its parent, but in a different GC.

WinDestroyWindow (win: winWindow) Destroys a window and all its subwindows, freeing contexts. This operation has no effect on a top-level window.

WinClose (win: winWindow) Destroys a top-level window and all its subwindows, frees the associated X resources, and closes its connection to the X server.

WinNewContext (oldwin: winWindow) returns newwin: winWindow Creates a new context window from an existing window. The context window appears as a ``window'' and points to the original window except it cannot generate any window events and it has a different graphics context.

WinCopyContext (srcwin, destwin: winWindow) Copies all information associated with srcwin's graphics context to that of destwin's.

WinSetBorder (win: winWindow; width: int; color: winColor) Sets the window border width and paints it using color. The border is not included when creating a window.

WinSetLabels (win: winWindow; winlab, iconlab: string[*]) Sets the window and icon labels.

WinMapWindow (win: winWindow)
WinMapSubwindows (win: winWindow)
WinUnmapWindow (win: winWindow)
WinUnmapSubwindows (win: winWindow) Maps or unmaps a window and/or all of its subwindows. Mapping a window onto the screen makes it and its subwindows visible; unmapping a window makes it and its subwindows invisible. Output to an unmapped window is allowed; when the window is remapped, its contents reflect such output.

WinMoveWindow (win: winWindow; pt: winPoint) Moves the window to the given location relative to its parent.

WinEnableOutput (win: winWindow)
WinDisableOutput (win: winWindow)
WinUpdateWindow (win: winWindow) Normally, output to an on a on-screen window is directed simultaneously to the window and to its backing pixmap. This can be disabled for performance reasons so that the output goes only to the pixmap; the window is then updated from the pixmap when WinUpdateWindow() is called.

WinFlush (win: winWindow) Flushes all pending output for a window and its subwindows.

WinSync (win: winWindow; discard: bool) Flushes the output buffer and waits for all requests to be received and processed by the X server. If discard is true, all pending window events not recognized by MPDWin are discarded.

WinBell (win: winWindow; percent: int) Rings the bell on the specified window, if possible. Volume is specified by the percentage relative to the base volume set by xset(1). Percent can be in the range -100 to 100 inclusive. If it is positive, the sound is louder than the base volume; if it is negative, the sound is quieter.

Cursors and Fonts

WinCreateCursor (win: winWindow; stdcursor: winStdCursor) returns cur: winCursor Creates a standard cursor. Valid cursors are:
XC_X_cursor	XC_arrow
XC_based_arrow_down	XC_based_arrow_up
XC_boat	XC_bogosity
XC_bottom_left_corner	XC_bottom_right_corner
XC_bottom_side	XC_bottom_tee
XC_box_spiral	XC_center_ptr
XC_circle	XC_clock
XC_coffee_mug	XC_cross
XC_cross_reverse	XC_crosshair
XC_diamond_cross	XC_dot
XC_dotbox	XC_double_arrow
XC_draft_large	XC_draft_small
XC_draped_box	XC_exchange
XC_fleur	XC_gobbler
XC_gumby	XC_hand1
XC_hand2	XC_heart
XC_icon	XC_iron_cross
XC_left_ptr	XC_left_side
XC_left_tee	XC_leftbutton
XC_ll_angle	XC_lr_angle
XC_man	XC_middlebutton
XC_mouse	XC_pencil
XC_pirate	XC_plus
XC_question_arrow	XC_right_ptr
XC_right_side	XC_right_tee
XC_rightbutton	XC_rtl_logo
XC_sailboat	XC_sb_down_arrow
XC_sb_h_double_arrow	XC_sb_left_arrow
XC_sb_right_arrow	XC_sb_up_arrow
XC_sb_v_double_arrow	XC_shuttle
XC_sizing	XC_spider
XC_spraycan	XC_star
XC_target	XC_tcross
XC_top_left_arrow	XC_top_left_corner
XC_top_right_corner	XC_top_side
XC_top_tee	XC_trek
XC_ul_angle	XC_umbrella
XC_ur_angle	XC_watch
XC_xterm	XC_None

WinSetCursor (win: winWindow; cursor: winCursor; fg, bg: winColor) returns c: winCursor Sets the cursor of the specified window, returning null if unsuccessful. The cursor colors are set to fg (foreground) and bg (background).

WinFreeCursor (win: winWindow; cursor: winCursor) Frees a cursor and reclaims any associated resources.

WinDefaultFont (win: winWindow) returns font: winFont Returns the default font of the graphics context.

WinLoadFont (win: winWindow; fontname: string[*]) returns font: winFont Loads a font by name.

WinSetFont (win: winWindow; font: winFont) Sets the font for the specified window.

WinFreeFont (win: winWindow; font: winFont) Frees a font and reclaims any associated resources. The default font cannot be freed.

Clipping Manipulation Function

WinSetClipRectangles (win: winWindow; origin: winPoint; rects[*]: winRectangle) Sets the clipping region for a context window (clip rectangles are stored on a per-context basis). Subsequent output is clipped to be contained within the specified nonintersecting rectangles. The parameter origin is relative to the origin of the window, and the rectangle coordinates are relative to the clip origin.

Drawing Functions

WinClearArea (win: winWindow; area: winRectangle) Clears a rectangular region using the window background color (which can differ from the current value set by WinSetBackground()). The clipping attributes of the context window are ignored.

WinEraseArea (win: winWindow; area: winRectangle) Clears a rectangular area to the current graphics context background color, which is set using WinSetBackground().

WinCopyArea (srcw, destw: winWindow; src_rect: winRectangle; destp: winPoint) Copies a rectangular region between (potentially) two windows on the same physical screen.

WinDrawArc (win: winWindow; box: winRectangle; a1, a2: int)
WinFillArc (win: winWindow; box: winRectangle; a1, a2: int) Draws a (filled) arc, ellipse, or circle. The center of the circle or ellipse is the center of the rectangle. The major and minor axes are given by the width and height of the rectangle. The two angles are in units of degrees. The first angle specifies the start of the arc; the second specifies the path and extent of the arc, with positive values indicating a counterclockwise direction.

WinDrawLine (win: winWindow; pt1, pt2: winPoint)
WinDrawPolyline (win: winWindow; pts[*]: winPoint)
WinDrawPolygon (win: winWindow; pts[*]: winPoint)
WinFillPolygon (win: winWindow; pts[*]: winPoint) Draws a (filled) line, polyline, or polygon.

WinDrawPixel (win: winWindow; pt: winPoint) Draws a pixel.

WinDrawRectangle (win: winWindow; rect: winRectangle)
WinFillRectangle (win: winWindow; rect: winRectangle) Draws a (filled) box.

WinDrawString (win: winWindow; pt: winPoint; str: string[*])
WinDrawImageString (win: winWindow; pt: winPoint; str: string[*]) Draws a string. WinDrawString() alters only the pixels forming the characters of the text; WinDrawImageString() clears the ``extent'' of the text to the background color.

WinTextWidth (font: winFont; str: string[*]) returns width: int Computes the pixel width of a string in that font.

WinFontAscent (font: winFont) returns ascent: int
WinFontDescent (font: winFont) returns descent: int Returns the ascent or descent of a font.

Drawing Attributes Manipulation Functions

WinSetLineAttr (win: winWindow; line_width: int; l: winLineStyle; c: winCapStyle; j: winJoinStyle)
WinSetFillAttr (win: winWindow; fill_style: winFillStyle; fill_rule: winFillRule)
WinSetDashes (win: winWindow; dash_offset: int; dash_list: string[*])
WinSetArcMode (win: winWindow; arc_mode: winArcMode)
WinSetDrawOp (win: winWindow; dop: winDrawOp) Sets the line drawing characteristics of a window. Constants include:
    winLineStyle:	LineSolid, LineDoubleDash, LineOnOffDash
    winCapStyle:	CapNotLast, CapButt, CapRound, CapProjecting
    winJoinStyle:	JoinMiter, JoinRound, JoinBevel
    winFillStyle:	FillSolid, FillTiled, FillOpaqueStippled, FillStippled
    winFillRule:	FillEvenOddRule, FillWindingRule
    winArcMode:	ArcChord, ArcPieSlice
    winDrawOp:
        Op_Clear, Op_And, Op_AndReverse, Op_Copy, Op_AndInverted, Op_Noop, Op_Xor, Op_Or, Op_Nor, Op_Equiv, Op_Invert, Op_OrReverse, Op_CopyInverted, Op_OrInverted, Op_Nand, Op_Set

    The defaults are line width 0, LineSolid, CapButt, JoinMiter, FillSolid, FillEvenOddRule, ArcPieSlice, Op_Copy, and no dashes.

    Using a line width other than zero may degrade performance on some X servers.

    Drawing operations other than Op_Copy are potentially nonportable or even undefined and should be used only with a clear understanding of the X color model. For example, Op_Xor gives different results (other things being equal) on Sun and DEC hardware.

WinSetForeground (win: winWindow; foreground: winColor) returns pv: winPixel
WinSetBackground (win: winWindow; background: winColor) returns pv: winPixel
WinSetForegroundByPixel (win: winWindow; foreground: winPixel)
WinSetBackgroundByPixel (win: winWindow; background: winPixel) Sets the foreground or background color to be used in subsequent drawing operations.

Event Handling Functions

WinSetPoll (win: winWindow; msec: int) Sets the interval between event checks, in milliseconds. The default interval is 100 milliseconds.

WinSetEventMask (win: winWindow; em: int) Registers events of interest for a window. Valid event masks are the same as the event types. They can be or'ed together to set multiple masks for a window. The default event masks include all supported event types if an event channel is provided at the window creation time, or nothing if no channel is provided and the window is requested to be mapped. There are several defined events masks:
    	Ev_KeyDown	Ev_EnterWindow	Ev_All
    	Ev_KeyUp	Ev_PointerMove	Ev_None
    	Ev_ButtonDown	Ev_ExitWindow
    	Ev_ButtonUp	Ev_DeleteWindow

    Ev_DeleteWindow is sent whenever the window manager issues a DELETE_WINDOW message (e.g. the user chooses Quit from window manager's menu); this event can only be received in the top-level window. Ev_All is the combination of all possible events; Ev_None selects no events.

Image Manipulation Functions

WinCreateImage (win: winWindow; depth, w, h: int) returns im: winImage Creates an image with width w and height h. If UseDefault is passed as depth, the depth of the image is set to be the same as that of the physical display.

WinDestroyImage (im: winImage) Destroys the image and frees the memory space it occupies.

WinGetPixel (im: winImage; pt: winPoint) returns pv: winPixel
WinPutPixel (im: winImage; pt: winPoint; pv: winPixel) Reads or writes a pixel value from or to the image. The point must be inside the image. These two functions are not protected by mutual exclusion; the application program should be aware of potential consistency problems when an image is shared among multiple processes. WinPutPixel() is most reliable when different processes work on different rows (and therefore different memory words).

WinAddPixel (im: winImage; pv: winPixel) Increments each pixel in the image by the value of pv. This function is not protected by mutual exclusion.

WinGetImage (win: winWindow; im: winImage; src_rect: winRectangle; dest: winPoint)
WinPutImage (win: winWindow; im: winImage; src_rect: winRectangle; dest: winPoint) Copies the rectangular area specified by src_rect on the window to the image starting at point specified by dest, or copies an image to a window. The depth of the image and the window must match.

SEE ALSO

mpd(1), mpdl(1)

Qiang Alex Zhao, SRWin: A Graphics Library for SR. TR 93-14, Dept. of Computer Science, The University of Arizona, 1993. Included in the MPD distribution.

Adrian Nye, Xlib Programming Manual, Volume One, 3rd ed. O'Reilly & Associates, Inc., 1992, ISBN 1-56592-002-3.

Adrian Nye, Xlib Reference Manual, Volume Two, 3rd ed. O'Reilly & Associates, Inc., 1992, ISBN 1-56592-006-6.

Robert W. Scheifler and James Gettys, X Window System: The Complete Reference to Xlib, X Protocol, ICCCM, XLFD, 3rd ed. Digital Press, 1992, ISBN 1-55558-088-2.

CAVEATS

Numerous unexplained problems have been seen on the Sequent Symmetry.

Except on an SGI Iris, MPDWin does not function properly if MultiMPD is enabled.

AUTHOR
Qiang A. Zhao.

ACKNOWLEDGMENTS
SRWin was inspired by X-Icon, an X interface developed by Clint Jeffery for the Icon language. Many useful ideas came from the Winpack graphics library created by Scott Hudson.