From c00652934e4ec68016a152b9bea10273b0be8726 Mon Sep 17 00:00:00 2001 From: "Andrew Gallant (Ocelot)" Date: Thu, 10 May 2012 23:57:34 -0400 Subject: better docs --- nexgb/shape/shape.go | 147 ++++++++++++++++++++++++++++++++------------------- 1 file changed, 92 insertions(+), 55 deletions(-) (limited to 'nexgb/shape') diff --git a/nexgb/shape/shape.go b/nexgb/shape/shape.go index 97be0f7..664c5f4 100644 --- a/nexgb/shape/shape.go +++ b/nexgb/shape/shape.go @@ -2,7 +2,7 @@ package shape /* - This file was generated by shape.xml on May 10 2012 8:04:32pm EDT. + This file was generated by shape.xml on May 10 2012 11:56:19pm EDT. This file is automatically generated. Edit at your peril! */ @@ -82,9 +82,7 @@ type Op byte type Kind byte -// Event definition Notify (0) -// Size: 32 - +// Notify is the event number for a NotifyEvent. const Notify = 0 type NotifyEvent struct { @@ -100,7 +98,7 @@ type NotifyEvent struct { // padding: 11 bytes } -// Event read Notify +// NotifyEventNew constructs a NotifyEvent value that implements xgb.Event from a byte slice. func NotifyEventNew(buf []byte) xgb.Event { v := NotifyEvent{} b := 1 // don't read event number @@ -141,7 +139,7 @@ func NotifyEventNew(buf []byte) xgb.Event { return v } -// Event write Notify +// Bytes writes a NotifyEvent value to a byte slice. func (v NotifyEvent) Bytes() []byte { buf := make([]byte, 32) b := 0 @@ -185,12 +183,14 @@ func (v NotifyEvent) Bytes() []byte { return buf } -func (v NotifyEvent) ImplementsEvent() {} - +// SequenceId returns the sequence id attached to the Notify event. +// Events without a sequence number (KeymapNotify) return 0. +// This is mostly used internally. func (v NotifyEvent) SequenceId() uint16 { return v.Sequence } +// String is a rudimentary string representation of NotifyEvent. func (v NotifyEvent) String() string { fieldVals := make([]string, 0, 9) fieldVals = append(fieldVals, xgb.Sprintf("Sequence: %d", v.Sequence)) @@ -209,35 +209,37 @@ func init() { xgb.NewExtEventFuncs["SHAPE"][0] = NotifyEventNew } -// Request QueryVersion -// size: 4 +// QueryVersionCookie is a cookie used only for QueryVersion requests. type QueryVersionCookie struct { *xgb.Cookie } +// QueryVersion sends a checked request. +// If an error occurs, it will be returned with the reply by calling QueryVersionCookie.Reply() func QueryVersion(c *xgb.Conn) QueryVersionCookie { cookie := c.NewCookie(true, true) c.NewRequest(queryVersionRequest(c), cookie) return QueryVersionCookie{cookie} } +// QueryVersionUnchecked sends an unchecked request. +// If an error occurs, it can only be retrieved using xgb.WaitForEvent or xgb.PollForEvent. func QueryVersionUnchecked(c *xgb.Conn) QueryVersionCookie { cookie := c.NewCookie(false, true) c.NewRequest(queryVersionRequest(c), cookie) return QueryVersionCookie{cookie} } -// Request reply for QueryVersion -// size: 12 +// QueryVersionReply represents the data returned from a QueryVersion request. type QueryVersionReply struct { - Sequence uint16 - Length uint32 + Sequence uint16 // sequence number of the request for this reply + Length uint32 // number of bytes in this reply // padding: 1 bytes MajorVersion uint16 MinorVersion uint16 } -// Waits and reads reply data from request QueryVersion +// Reply blocks and returns the reply data for a QueryVersion request. func (cook QueryVersionCookie) Reply() (*QueryVersionReply, error) { buf, err := cook.Cookie.Reply() if err != nil { @@ -249,7 +251,7 @@ func (cook QueryVersionCookie) Reply() (*QueryVersionReply, error) { return queryVersionReply(buf), nil } -// Read reply into structure from buffer for QueryVersion +// queryVersionReply reads a byte slice into a QueryVersionReply value. func queryVersionReply(buf []byte) *QueryVersionReply { v := new(QueryVersionReply) b := 1 // skip reply determinant @@ -272,6 +274,7 @@ func queryVersionReply(buf []byte) *QueryVersionReply { } // Write request to wire for QueryVersion +// queryVersionRequest writes a QueryVersion request to a byte slice. func queryVersionRequest(c *xgb.Conn) []byte { size := 4 b := 0 @@ -289,30 +292,35 @@ func queryVersionRequest(c *xgb.Conn) []byte { return buf } -// Request Rectangles -// size: xgb.Pad((16 + xgb.Pad((len(Rectangles) * 8)))) +// RectanglesCookie is a cookie used only for Rectangles requests. type RectanglesCookie struct { *xgb.Cookie } -// Write request to wire for Rectangles +// Rectangles sends an unchecked request. +// If an error occurs, it can only be retrieved using xgb.WaitForEvent or xgb.PollForEvent. func Rectangles(c *xgb.Conn, Operation Op, DestinationKind Kind, Ordering byte, DestinationWindow xproto.Window, XOffset int16, YOffset int16, Rectangles []xproto.Rectangle) RectanglesCookie { cookie := c.NewCookie(false, false) c.NewRequest(rectanglesRequest(c, Operation, DestinationKind, Ordering, DestinationWindow, XOffset, YOffset, Rectangles), cookie) return RectanglesCookie{cookie} } +// RectanglesChecked sends a checked request. +// If an error occurs, it can be retrieved using RectanglesCookie.Check() func RectanglesChecked(c *xgb.Conn, Operation Op, DestinationKind Kind, Ordering byte, DestinationWindow xproto.Window, XOffset int16, YOffset int16, Rectangles []xproto.Rectangle) RectanglesCookie { cookie := c.NewCookie(true, false) c.NewRequest(rectanglesRequest(c, Operation, DestinationKind, Ordering, DestinationWindow, XOffset, YOffset, Rectangles), cookie) return RectanglesCookie{cookie} } +// Check returns an error if one occurred for checked requests that are not expecting a reply. +// This cannot be called for requests expecting a reply, nor for unchecked requests. func (cook RectanglesCookie) Check() error { return cook.Cookie.Check() } // Write request to wire for Rectangles +// rectanglesRequest writes a Rectangles request to a byte slice. func rectanglesRequest(c *xgb.Conn, Operation Op, DestinationKind Kind, Ordering byte, DestinationWindow xproto.Window, XOffset int16, YOffset int16, Rectangles []xproto.Rectangle) []byte { size := xgb.Pad((16 + xgb.Pad((len(Rectangles) * 8)))) b := 0 @@ -352,30 +360,35 @@ func rectanglesRequest(c *xgb.Conn, Operation Op, DestinationKind Kind, Ordering return buf } -// Request Mask -// size: 20 +// MaskCookie is a cookie used only for Mask requests. type MaskCookie struct { *xgb.Cookie } -// Write request to wire for Mask +// Mask sends an unchecked request. +// If an error occurs, it can only be retrieved using xgb.WaitForEvent or xgb.PollForEvent. func Mask(c *xgb.Conn, Operation Op, DestinationKind Kind, DestinationWindow xproto.Window, XOffset int16, YOffset int16, SourceBitmap xproto.Pixmap) MaskCookie { cookie := c.NewCookie(false, false) c.NewRequest(maskRequest(c, Operation, DestinationKind, DestinationWindow, XOffset, YOffset, SourceBitmap), cookie) return MaskCookie{cookie} } +// MaskChecked sends a checked request. +// If an error occurs, it can be retrieved using MaskCookie.Check() func MaskChecked(c *xgb.Conn, Operation Op, DestinationKind Kind, DestinationWindow xproto.Window, XOffset int16, YOffset int16, SourceBitmap xproto.Pixmap) MaskCookie { cookie := c.NewCookie(true, false) c.NewRequest(maskRequest(c, Operation, DestinationKind, DestinationWindow, XOffset, YOffset, SourceBitmap), cookie) return MaskCookie{cookie} } +// Check returns an error if one occurred for checked requests that are not expecting a reply. +// This cannot be called for requests expecting a reply, nor for unchecked requests. func (cook MaskCookie) Check() error { return cook.Cookie.Check() } // Write request to wire for Mask +// maskRequest writes a Mask request to a byte slice. func maskRequest(c *xgb.Conn, Operation Op, DestinationKind Kind, DestinationWindow xproto.Window, XOffset int16, YOffset int16, SourceBitmap xproto.Pixmap) []byte { size := 20 b := 0 @@ -413,30 +426,35 @@ func maskRequest(c *xgb.Conn, Operation Op, DestinationKind Kind, DestinationWin return buf } -// Request Combine -// size: 20 +// CombineCookie is a cookie used only for Combine requests. type CombineCookie struct { *xgb.Cookie } -// Write request to wire for Combine +// Combine sends an unchecked request. +// If an error occurs, it can only be retrieved using xgb.WaitForEvent or xgb.PollForEvent. func Combine(c *xgb.Conn, Operation Op, DestinationKind Kind, SourceKind Kind, DestinationWindow xproto.Window, XOffset int16, YOffset int16, SourceWindow xproto.Window) CombineCookie { cookie := c.NewCookie(false, false) c.NewRequest(combineRequest(c, Operation, DestinationKind, SourceKind, DestinationWindow, XOffset, YOffset, SourceWindow), cookie) return CombineCookie{cookie} } +// CombineChecked sends a checked request. +// If an error occurs, it can be retrieved using CombineCookie.Check() func CombineChecked(c *xgb.Conn, Operation Op, DestinationKind Kind, SourceKind Kind, DestinationWindow xproto.Window, XOffset int16, YOffset int16, SourceWindow xproto.Window) CombineCookie { cookie := c.NewCookie(true, false) c.NewRequest(combineRequest(c, Operation, DestinationKind, SourceKind, DestinationWindow, XOffset, YOffset, SourceWindow), cookie) return CombineCookie{cookie} } +// Check returns an error if one occurred for checked requests that are not expecting a reply. +// This cannot be called for requests expecting a reply, nor for unchecked requests. func (cook CombineCookie) Check() error { return cook.Cookie.Check() } // Write request to wire for Combine +// combineRequest writes a Combine request to a byte slice. func combineRequest(c *xgb.Conn, Operation Op, DestinationKind Kind, SourceKind Kind, DestinationWindow xproto.Window, XOffset int16, YOffset int16, SourceWindow xproto.Window) []byte { size := 20 b := 0 @@ -477,30 +495,35 @@ func combineRequest(c *xgb.Conn, Operation Op, DestinationKind Kind, SourceKind return buf } -// Request Offset -// size: 16 +// OffsetCookie is a cookie used only for Offset requests. type OffsetCookie struct { *xgb.Cookie } -// Write request to wire for Offset +// Offset sends an unchecked request. +// If an error occurs, it can only be retrieved using xgb.WaitForEvent or xgb.PollForEvent. func Offset(c *xgb.Conn, DestinationKind Kind, DestinationWindow xproto.Window, XOffset int16, YOffset int16) OffsetCookie { cookie := c.NewCookie(false, false) c.NewRequest(offsetRequest(c, DestinationKind, DestinationWindow, XOffset, YOffset), cookie) return OffsetCookie{cookie} } +// OffsetChecked sends a checked request. +// If an error occurs, it can be retrieved using OffsetCookie.Check() func OffsetChecked(c *xgb.Conn, DestinationKind Kind, DestinationWindow xproto.Window, XOffset int16, YOffset int16) OffsetCookie { cookie := c.NewCookie(true, false) c.NewRequest(offsetRequest(c, DestinationKind, DestinationWindow, XOffset, YOffset), cookie) return OffsetCookie{cookie} } +// Check returns an error if one occurred for checked requests that are not expecting a reply. +// This cannot be called for requests expecting a reply, nor for unchecked requests. func (cook OffsetCookie) Check() error { return cook.Cookie.Check() } // Write request to wire for Offset +// offsetRequest writes a Offset request to a byte slice. func offsetRequest(c *xgb.Conn, DestinationKind Kind, DestinationWindow xproto.Window, XOffset int16, YOffset int16) []byte { size := 16 b := 0 @@ -532,29 +555,31 @@ func offsetRequest(c *xgb.Conn, DestinationKind Kind, DestinationWindow xproto.W return buf } -// Request QueryExtents -// size: 8 +// QueryExtentsCookie is a cookie used only for QueryExtents requests. type QueryExtentsCookie struct { *xgb.Cookie } +// QueryExtents sends a checked request. +// If an error occurs, it will be returned with the reply by calling QueryExtentsCookie.Reply() func QueryExtents(c *xgb.Conn, DestinationWindow xproto.Window) QueryExtentsCookie { cookie := c.NewCookie(true, true) c.NewRequest(queryExtentsRequest(c, DestinationWindow), cookie) return QueryExtentsCookie{cookie} } +// QueryExtentsUnchecked sends an unchecked request. +// If an error occurs, it can only be retrieved using xgb.WaitForEvent or xgb.PollForEvent. func QueryExtentsUnchecked(c *xgb.Conn, DestinationWindow xproto.Window) QueryExtentsCookie { cookie := c.NewCookie(false, true) c.NewRequest(queryExtentsRequest(c, DestinationWindow), cookie) return QueryExtentsCookie{cookie} } -// Request reply for QueryExtents -// size: 28 +// QueryExtentsReply represents the data returned from a QueryExtents request. type QueryExtentsReply struct { - Sequence uint16 - Length uint32 + Sequence uint16 // sequence number of the request for this reply + Length uint32 // number of bytes in this reply // padding: 1 bytes BoundingShaped bool ClipShaped bool @@ -569,7 +594,7 @@ type QueryExtentsReply struct { ClipShapeExtentsHeight uint16 } -// Waits and reads reply data from request QueryExtents +// Reply blocks and returns the reply data for a QueryExtents request. func (cook QueryExtentsCookie) Reply() (*QueryExtentsReply, error) { buf, err := cook.Cookie.Reply() if err != nil { @@ -581,7 +606,7 @@ func (cook QueryExtentsCookie) Reply() (*QueryExtentsReply, error) { return queryExtentsReply(buf), nil } -// Read reply into structure from buffer for QueryExtents +// queryExtentsReply reads a byte slice into a QueryExtentsReply value. func queryExtentsReply(buf []byte) *QueryExtentsReply { v := new(QueryExtentsReply) b := 1 // skip reply determinant @@ -638,6 +663,7 @@ func queryExtentsReply(buf []byte) *QueryExtentsReply { } // Write request to wire for QueryExtents +// queryExtentsRequest writes a QueryExtents request to a byte slice. func queryExtentsRequest(c *xgb.Conn, DestinationWindow xproto.Window) []byte { size := 8 b := 0 @@ -658,30 +684,35 @@ func queryExtentsRequest(c *xgb.Conn, DestinationWindow xproto.Window) []byte { return buf } -// Request SelectInput -// size: 12 +// SelectInputCookie is a cookie used only for SelectInput requests. type SelectInputCookie struct { *xgb.Cookie } -// Write request to wire for SelectInput +// SelectInput sends an unchecked request. +// If an error occurs, it can only be retrieved using xgb.WaitForEvent or xgb.PollForEvent. func SelectInput(c *xgb.Conn, DestinationWindow xproto.Window, Enable bool) SelectInputCookie { cookie := c.NewCookie(false, false) c.NewRequest(selectInputRequest(c, DestinationWindow, Enable), cookie) return SelectInputCookie{cookie} } +// SelectInputChecked sends a checked request. +// If an error occurs, it can be retrieved using SelectInputCookie.Check() func SelectInputChecked(c *xgb.Conn, DestinationWindow xproto.Window, Enable bool) SelectInputCookie { cookie := c.NewCookie(true, false) c.NewRequest(selectInputRequest(c, DestinationWindow, Enable), cookie) return SelectInputCookie{cookie} } +// Check returns an error if one occurred for checked requests that are not expecting a reply. +// This cannot be called for requests expecting a reply, nor for unchecked requests. func (cook SelectInputCookie) Check() error { return cook.Cookie.Check() } // Write request to wire for SelectInput +// selectInputRequest writes a SelectInput request to a byte slice. func selectInputRequest(c *xgb.Conn, DestinationWindow xproto.Window, Enable bool) []byte { size := 12 b := 0 @@ -711,33 +742,35 @@ func selectInputRequest(c *xgb.Conn, DestinationWindow xproto.Window, Enable boo return buf } -// Request InputSelected -// size: 8 +// InputSelectedCookie is a cookie used only for InputSelected requests. type InputSelectedCookie struct { *xgb.Cookie } +// InputSelected sends a checked request. +// If an error occurs, it will be returned with the reply by calling InputSelectedCookie.Reply() func InputSelected(c *xgb.Conn, DestinationWindow xproto.Window) InputSelectedCookie { cookie := c.NewCookie(true, true) c.NewRequest(inputSelectedRequest(c, DestinationWindow), cookie) return InputSelectedCookie{cookie} } +// InputSelectedUnchecked sends an unchecked request. +// If an error occurs, it can only be retrieved using xgb.WaitForEvent or xgb.PollForEvent. func InputSelectedUnchecked(c *xgb.Conn, DestinationWindow xproto.Window) InputSelectedCookie { cookie := c.NewCookie(false, true) c.NewRequest(inputSelectedRequest(c, DestinationWindow), cookie) return InputSelectedCookie{cookie} } -// Request reply for InputSelected -// size: 8 +// InputSelectedReply represents the data returned from a InputSelected request. type InputSelectedReply struct { - Sequence uint16 - Length uint32 + Sequence uint16 // sequence number of the request for this reply + Length uint32 // number of bytes in this reply Enabled bool } -// Waits and reads reply data from request InputSelected +// Reply blocks and returns the reply data for a InputSelected request. func (cook InputSelectedCookie) Reply() (*InputSelectedReply, error) { buf, err := cook.Cookie.Reply() if err != nil { @@ -749,7 +782,7 @@ func (cook InputSelectedCookie) Reply() (*InputSelectedReply, error) { return inputSelectedReply(buf), nil } -// Read reply into structure from buffer for InputSelected +// inputSelectedReply reads a byte slice into a InputSelectedReply value. func inputSelectedReply(buf []byte) *InputSelectedReply { v := new(InputSelectedReply) b := 1 // skip reply determinant @@ -771,6 +804,7 @@ func inputSelectedReply(buf []byte) *InputSelectedReply { } // Write request to wire for InputSelected +// inputSelectedRequest writes a InputSelected request to a byte slice. func inputSelectedRequest(c *xgb.Conn, DestinationWindow xproto.Window) []byte { size := 8 b := 0 @@ -791,36 +825,38 @@ func inputSelectedRequest(c *xgb.Conn, DestinationWindow xproto.Window) []byte { return buf } -// Request GetRectangles -// size: 12 +// GetRectanglesCookie is a cookie used only for GetRectangles requests. type GetRectanglesCookie struct { *xgb.Cookie } +// GetRectangles sends a checked request. +// If an error occurs, it will be returned with the reply by calling GetRectanglesCookie.Reply() func GetRectangles(c *xgb.Conn, Window xproto.Window, SourceKind Kind) GetRectanglesCookie { cookie := c.NewCookie(true, true) c.NewRequest(getRectanglesRequest(c, Window, SourceKind), cookie) return GetRectanglesCookie{cookie} } +// GetRectanglesUnchecked sends an unchecked request. +// If an error occurs, it can only be retrieved using xgb.WaitForEvent or xgb.PollForEvent. func GetRectanglesUnchecked(c *xgb.Conn, Window xproto.Window, SourceKind Kind) GetRectanglesCookie { cookie := c.NewCookie(false, true) c.NewRequest(getRectanglesRequest(c, Window, SourceKind), cookie) return GetRectanglesCookie{cookie} } -// Request reply for GetRectangles -// size: (32 + xgb.Pad((int(RectanglesLen) * 8))) +// GetRectanglesReply represents the data returned from a GetRectangles request. type GetRectanglesReply struct { - Sequence uint16 - Length uint32 + Sequence uint16 // sequence number of the request for this reply + Length uint32 // number of bytes in this reply Ordering byte RectanglesLen uint32 // padding: 20 bytes Rectangles []xproto.Rectangle // size: xgb.Pad((int(RectanglesLen) * 8)) } -// Waits and reads reply data from request GetRectangles +// Reply blocks and returns the reply data for a GetRectangles request. func (cook GetRectanglesCookie) Reply() (*GetRectanglesReply, error) { buf, err := cook.Cookie.Reply() if err != nil { @@ -832,7 +868,7 @@ func (cook GetRectanglesCookie) Reply() (*GetRectanglesReply, error) { return getRectanglesReply(buf), nil } -// Read reply into structure from buffer for GetRectangles +// getRectanglesReply reads a byte slice into a GetRectanglesReply value. func getRectanglesReply(buf []byte) *GetRectanglesReply { v := new(GetRectanglesReply) b := 1 // skip reply determinant @@ -858,6 +894,7 @@ func getRectanglesReply(buf []byte) *GetRectanglesReply { } // Write request to wire for GetRectangles +// getRectanglesRequest writes a GetRectangles request to a byte slice. func getRectanglesRequest(c *xgb.Conn, Window xproto.Window, SourceKind Kind) []byte { size := 12 b := 0 -- cgit v1.2.3-70-g09d2