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/screensaver/screensaver.go | 106 ++++++++++++++++++++++++--------------- 1 file changed, 66 insertions(+), 40 deletions(-) (limited to 'nexgb/screensaver') diff --git a/nexgb/screensaver/screensaver.go b/nexgb/screensaver/screensaver.go index f11113e..0b6ef23 100644 --- a/nexgb/screensaver/screensaver.go +++ b/nexgb/screensaver/screensaver.go @@ -2,7 +2,7 @@ package screensaver /* - This file was generated by screensaver.xml on May 10 2012 8:04:32pm EDT. + This file was generated by screensaver.xml on May 10 2012 11:56:19pm EDT. This file is automatically generated. Edit at your peril! */ @@ -40,6 +40,10 @@ func init() { xgb.NewExtErrorFuncs["MIT-SCREEN-SAVER"] = make(map[int]xgb.NewErrorFun) } +// Skipping definition for base type 'Card32' + +// Skipping definition for base type 'Double' + // Skipping definition for base type 'Bool' // Skipping definition for base type 'Float' @@ -60,10 +64,6 @@ func init() { // Skipping definition for base type 'Char' -// Skipping definition for base type 'Card32' - -// Skipping definition for base type 'Double' - const ( KindBlanked = 0 KindInternal = 1 @@ -82,9 +82,7 @@ const ( StateDisabled = 3 ) -// Event definition Notify (0) -// Size: 32 - +// Notify is the event number for a NotifyEvent. const Notify = 0 type NotifyEvent struct { @@ -101,7 +99,7 @@ type NotifyEvent struct { // padding: 14 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 @@ -144,7 +142,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 @@ -190,12 +188,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, 10) fieldVals = append(fieldVals, xgb.Sprintf("Sequence: %d", v.Sequence)) @@ -214,36 +214,38 @@ func init() { xgb.NewExtEventFuncs["MIT-SCREEN-SAVER"][0] = NotifyEventNew } -// Request QueryVersion -// size: 8 +// 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, ClientMajorVersion byte, ClientMinorVersion byte) QueryVersionCookie { cookie := c.NewCookie(true, true) c.NewRequest(queryVersionRequest(c, ClientMajorVersion, ClientMinorVersion), 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, ClientMajorVersion byte, ClientMinorVersion byte) QueryVersionCookie { cookie := c.NewCookie(false, true) c.NewRequest(queryVersionRequest(c, ClientMajorVersion, ClientMinorVersion), cookie) return QueryVersionCookie{cookie} } -// Request reply for QueryVersion -// size: 32 +// 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 ServerMajorVersion uint16 ServerMinorVersion uint16 // padding: 20 bytes } -// 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 { @@ -255,7 +257,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 @@ -280,6 +282,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, ClientMajorVersion byte, ClientMinorVersion byte) []byte { size := 8 b := 0 @@ -305,29 +308,31 @@ func queryVersionRequest(c *xgb.Conn, ClientMajorVersion byte, ClientMinorVersio return buf } -// Request QueryInfo -// size: 8 +// QueryInfoCookie is a cookie used only for QueryInfo requests. type QueryInfoCookie struct { *xgb.Cookie } +// QueryInfo sends a checked request. +// If an error occurs, it will be returned with the reply by calling QueryInfoCookie.Reply() func QueryInfo(c *xgb.Conn, Drawable xproto.Drawable) QueryInfoCookie { cookie := c.NewCookie(true, true) c.NewRequest(queryInfoRequest(c, Drawable), cookie) return QueryInfoCookie{cookie} } +// QueryInfoUnchecked sends an unchecked request. +// If an error occurs, it can only be retrieved using xgb.WaitForEvent or xgb.PollForEvent. func QueryInfoUnchecked(c *xgb.Conn, Drawable xproto.Drawable) QueryInfoCookie { cookie := c.NewCookie(false, true) c.NewRequest(queryInfoRequest(c, Drawable), cookie) return QueryInfoCookie{cookie} } -// Request reply for QueryInfo -// size: 32 +// QueryInfoReply represents the data returned from a QueryInfo request. type QueryInfoReply struct { - Sequence uint16 - Length uint32 + Sequence uint16 // sequence number of the request for this reply + Length uint32 // number of bytes in this reply State byte SaverWindow xproto.Window MsUntilServer uint32 @@ -337,7 +342,7 @@ type QueryInfoReply struct { // padding: 7 bytes } -// Waits and reads reply data from request QueryInfo +// Reply blocks and returns the reply data for a QueryInfo request. func (cook QueryInfoCookie) Reply() (*QueryInfoReply, error) { buf, err := cook.Cookie.Reply() if err != nil { @@ -349,7 +354,7 @@ func (cook QueryInfoCookie) Reply() (*QueryInfoReply, error) { return queryInfoReply(buf), nil } -// Read reply into structure from buffer for QueryInfo +// queryInfoReply reads a byte slice into a QueryInfoReply value. func queryInfoReply(buf []byte) *QueryInfoReply { v := new(QueryInfoReply) b := 1 // skip reply determinant @@ -384,6 +389,7 @@ func queryInfoReply(buf []byte) *QueryInfoReply { } // Write request to wire for QueryInfo +// queryInfoRequest writes a QueryInfo request to a byte slice. func queryInfoRequest(c *xgb.Conn, Drawable xproto.Drawable) []byte { size := 8 b := 0 @@ -404,30 +410,35 @@ func queryInfoRequest(c *xgb.Conn, Drawable xproto.Drawable) []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, Drawable xproto.Drawable, EventMask uint32) SelectInputCookie { cookie := c.NewCookie(false, false) c.NewRequest(selectInputRequest(c, Drawable, EventMask), 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, Drawable xproto.Drawable, EventMask uint32) SelectInputCookie { cookie := c.NewCookie(true, false) c.NewRequest(selectInputRequest(c, Drawable, EventMask), 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, Drawable xproto.Drawable, EventMask uint32) []byte { size := 12 b := 0 @@ -451,30 +462,35 @@ func selectInputRequest(c *xgb.Conn, Drawable xproto.Drawable, EventMask uint32) return buf } -// Request SetAttributes -// size: xgb.Pad((24 + (4 + xgb.Pad((4 * xgb.PopCount(int(ValueMask))))))) +// SetAttributesCookie is a cookie used only for SetAttributes requests. type SetAttributesCookie struct { *xgb.Cookie } -// Write request to wire for SetAttributes +// SetAttributes sends an unchecked request. +// If an error occurs, it can only be retrieved using xgb.WaitForEvent or xgb.PollForEvent. func SetAttributes(c *xgb.Conn, Drawable xproto.Drawable, X int16, Y int16, Width uint16, Height uint16, BorderWidth uint16, Class byte, Depth byte, Visual xproto.Visualid, ValueMask uint32, ValueList []uint32) SetAttributesCookie { cookie := c.NewCookie(false, false) c.NewRequest(setAttributesRequest(c, Drawable, X, Y, Width, Height, BorderWidth, Class, Depth, Visual, ValueMask, ValueList), cookie) return SetAttributesCookie{cookie} } +// SetAttributesChecked sends a checked request. +// If an error occurs, it can be retrieved using SetAttributesCookie.Check() func SetAttributesChecked(c *xgb.Conn, Drawable xproto.Drawable, X int16, Y int16, Width uint16, Height uint16, BorderWidth uint16, Class byte, Depth byte, Visual xproto.Visualid, ValueMask uint32, ValueList []uint32) SetAttributesCookie { cookie := c.NewCookie(true, false) c.NewRequest(setAttributesRequest(c, Drawable, X, Y, Width, Height, BorderWidth, Class, Depth, Visual, ValueMask, ValueList), cookie) return SetAttributesCookie{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 SetAttributesCookie) Check() error { return cook.Cookie.Check() } // Write request to wire for SetAttributes +// setAttributesRequest writes a SetAttributes request to a byte slice. func setAttributesRequest(c *xgb.Conn, Drawable xproto.Drawable, X int16, Y int16, Width uint16, Height uint16, BorderWidth uint16, Class byte, Depth byte, Visual xproto.Visualid, ValueMask uint32, ValueList []uint32) []byte { size := xgb.Pad((24 + (4 + xgb.Pad((4 * xgb.PopCount(int(ValueMask))))))) b := 0 @@ -527,30 +543,35 @@ func setAttributesRequest(c *xgb.Conn, Drawable xproto.Drawable, X int16, Y int1 return buf } -// Request UnsetAttributes -// size: 8 +// UnsetAttributesCookie is a cookie used only for UnsetAttributes requests. type UnsetAttributesCookie struct { *xgb.Cookie } -// Write request to wire for UnsetAttributes +// UnsetAttributes sends an unchecked request. +// If an error occurs, it can only be retrieved using xgb.WaitForEvent or xgb.PollForEvent. func UnsetAttributes(c *xgb.Conn, Drawable xproto.Drawable) UnsetAttributesCookie { cookie := c.NewCookie(false, false) c.NewRequest(unsetAttributesRequest(c, Drawable), cookie) return UnsetAttributesCookie{cookie} } +// UnsetAttributesChecked sends a checked request. +// If an error occurs, it can be retrieved using UnsetAttributesCookie.Check() func UnsetAttributesChecked(c *xgb.Conn, Drawable xproto.Drawable) UnsetAttributesCookie { cookie := c.NewCookie(true, false) c.NewRequest(unsetAttributesRequest(c, Drawable), cookie) return UnsetAttributesCookie{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 UnsetAttributesCookie) Check() error { return cook.Cookie.Check() } // Write request to wire for UnsetAttributes +// unsetAttributesRequest writes a UnsetAttributes request to a byte slice. func unsetAttributesRequest(c *xgb.Conn, Drawable xproto.Drawable) []byte { size := 8 b := 0 @@ -571,30 +592,35 @@ func unsetAttributesRequest(c *xgb.Conn, Drawable xproto.Drawable) []byte { return buf } -// Request Suspend -// size: 8 +// SuspendCookie is a cookie used only for Suspend requests. type SuspendCookie struct { *xgb.Cookie } -// Write request to wire for Suspend +// Suspend sends an unchecked request. +// If an error occurs, it can only be retrieved using xgb.WaitForEvent or xgb.PollForEvent. func Suspend(c *xgb.Conn, Suspend bool) SuspendCookie { cookie := c.NewCookie(false, false) c.NewRequest(suspendRequest(c, Suspend), cookie) return SuspendCookie{cookie} } +// SuspendChecked sends a checked request. +// If an error occurs, it can be retrieved using SuspendCookie.Check() func SuspendChecked(c *xgb.Conn, Suspend bool) SuspendCookie { cookie := c.NewCookie(true, false) c.NewRequest(suspendRequest(c, Suspend), cookie) return SuspendCookie{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 SuspendCookie) Check() error { return cook.Cookie.Check() } // Write request to wire for Suspend +// suspendRequest writes a Suspend request to a byte slice. func suspendRequest(c *xgb.Conn, Suspend bool) []byte { size := 8 b := 0 -- cgit v1.2.3-70-g09d2