diff --git a/canvas/canvas.go b/canvas/canvas.go index 691c0bb..ec0a7dc 100644 --- a/canvas/canvas.go +++ b/canvas/canvas.go @@ -8,24 +8,24 @@ import "image/color" // Cap represents a stroke cap type. type Cap int; const ( - CapButt Cap = iota - CapRound - CapSquare + CapButt Cap = iota // Square cap that ends at the point + CapRound // Round cap that surrounds the point + CapSquare // square cap that surrounds the point ) // Joint represents a stroke joint type. type Joint int; const ( - JointRount Joint = iota - JointSharp - JointMiter + JointRount Joint = iota // Rounded joint + JointSharp // Sharp joint + JointMiter // Clipped/beveled joint ) // StrokeAlign determines whether a stroke is drawn inside, outside, or on a // path. type StrokeAlign int; const ( - StrokeAlignCenter StrokeAlign = iota - StrokeAlignInner - StrokeAlignOuter + StrokeAlignCenter StrokeAlign = iota // Centered on the path + StrokeAlignInner // Inset into the path + StrokeAlignOuter // Outset around the path ) // Pen represents a drawing context that is linked to a canvas. Each canvas can @@ -44,9 +44,8 @@ type Pen interface { StrokeWeight (int) // how thick the stroke is StrokeAlign (StrokeAlign) // where the stroke is drawn - // set the stroke/fill to a solid color - Stroke (color.Color) - Fill (color.Color) + Stroke (color.Color) // Sets the stroke to a solid color + Fill (color.Color) // Sets the fill to a solid color } // Canvas is an image that supports drawing paths. @@ -62,6 +61,7 @@ type Canvas interface { // Drawer is an object that can draw to a canvas. type Drawer interface { + // Draw draws to the given canvas. Draw (Canvas) } diff --git a/data/data.go b/data/data.go index ab8e5da..101015f 100644 --- a/data/data.go +++ b/data/data.go @@ -27,7 +27,10 @@ func (mime Mime) String () string { return mime.Type + "/" + mime.Subtype } +// MimePlain returns the MIME type of plain text. func MimePlain () Mime { return Mime { "text", "plain" } } + +// MimeFile returns the MIME type of a file path/URI. func MimeFile () Mime { return Mime { "text", "uri-list" } } type byteReadCloser struct { *bytes.Reader } diff --git a/object.go b/object.go index 850db85..96e06b2 100644 --- a/object.go +++ b/object.go @@ -111,25 +111,66 @@ type Object interface { type Box interface { Object + // Window returns the Window this Box is a part of. Window () Window + // Bounds returns the outer bounding rectangle of the Box relative to + // the Window. Bounds () image.Rectangle + // InnerBounds returns the inner bounding rectangle of the box. It is + // the value of Bounds inset by the Box's border and padding. InnerBounds () image.Rectangle + // MinimumSize returns the minimum width and height this Box's bounds + // can be set to. This will return the value of whichever of these is + // greater: + // - The size as set by SetMinimumSize + // - The size taken up by the Box's border and padding. If there is + // internal content that does not overflow, the size of that is also + // taken into account here. MinimumSize () image.Point + // SetBounds sets the bounding rectangle of this Box relative to the + // Window. SetBounds (image.Rectangle) + // SetColor sets the background color of this Box. SetColor (color.Color) + // SetBorder sets the Border(s) of the box. The first Border will be the + // most outset, and the last Border will be the most inset. SetBorder (...Border) + // SetMinimumSize sets the minimum width and height of the box, as + // described in MinimumSize. SetMinimumSize (image.Point) + // SetPadding sets the padding between the Box's innermost Border and + // its content. SetPadding (Inset) + // SetDNDData sets the data that will be picked up if this Box is + // dragged. If this is nil (which is the default), this Box will not be + // picked up. SetDNDData (data.Data) + // SetDNDAccept sets the type of data that can be dropped onto this Box. + // If this is nil (which is the default), this Box will reject all + // drops. SetDNDAccept (...data.Mime) + // SetFocused sets whether or not this Box has keyboard focus. If set to + // true, this method will steal focus away from whichever Object + // currently has focus. SetFocused (bool) + // SetFocusable sets whether or not this Box can receive keyboard focus. + // If set to false and the Box is already focused. the focus is removed. SetFocusable (bool) - + + // Focused returns whether or not this Box has keyboard focus. Focused () bool + // Modifiers returns which modifier keys on the keyboard are currently + // being held down. Modifiers () input.Modifiers + // MousePosition returns the position of the mouse pointer relative to + // the Window. MousePosition () image.Point + // These are event subscription functions that allow callbacks to be + // connected to particular events. Multiple callbacks may be connected + // to the same event at once. Callbacks can be removed by closing the + // returned cookie. OnFocusEnter (func ()) event.Cookie OnFocusLeave (func ()) event.Cookie OnDNDEnter (func ()) event.Cookie @@ -148,7 +189,13 @@ type Box interface { // CanvasBox is a box that can be drawn to. type CanvasBox interface { Box + + // SetDrawer sets the Drawer that will be called upon to draw the Box's + // content when it is invalidated. SetDrawer (canvas.Drawer) + + // Invalidate causes the Box's area to be redrawn at the end of the + // event cycle, even if it wouldn't be otherwise. Invalidate () } @@ -156,77 +203,151 @@ type CanvasBox interface { // is to be embedded into TextBox and ContainerBox. type ContentBox interface { Box + + // SetOverflow sets whether or not the Box's content overflows + // horizontally and vertically. Overflowing content is clipped to the + // bounds of the Box inset by all Borders (but not padding). SetOverflow (horizontal, vertical bool) - ContentBounds () image.Rectangle - ScrollTo (image.Point) - OnContentBoundsChange (func ()) event.Cookie + // SetAlign sets how the Box's content is distributed horizontally and + // vertically. SetAlign (x, y Align) + // ContentBounds returns the bounds of the inner content of the Box + // relative to the window. + ContentBounds () image.Rectangle + // ScrollTo shifts the origin of the Box's content to the origin of the + // Box's InnerBounds, offset by the given point. + ScrollTo (image.Point) + // OnContentBoundsChange specifies a function to be called when the + // Box's ContentBounds or InnerBounds changes. + OnContentBoundsChange (func ()) event.Cookie } // TextBox is a box that contains text content. type TextBox interface { ContentBox + // SetText sets the text content of the Box. SetText (string) + // SetTextColor sets the text color. SetTextColor (color.Color) + // SetFace sets the font face text is rendered in. SetFace (font.Face) + // SetWrap sets whether or not the text wraps. SetWrap (bool) + // SetSelectable sets whether or not the text content can be + // highlighted/selected. SetSelectable (bool) + // Select sets the text cursor or selection. Select (text.Dot) + // Dot returns the text cursor or selection. Dot () text.Dot + // OnDotChange specifies a function to be called when the text cursor or + // selection changes. OnDotChange (func ()) event.Cookie } -// ContentBox is a box that can contain child objects. It arranges them +// ContentBox is a box that can contain child Objects. It arranges them // according to a layout rule. type ContainerBox interface { ContentBox - PropagateEvents (bool) - SetGap (image.Point) - Add (Object) - Delete (Object) - Insert (child Object, before Object) - Clear () - Length () int - At (int) Object - SetLayout (Layout) + + // SetPropagateEvents specifies whether or not child Objects will + // receive user input events. It is true by default. If it is false, all + // user input that would otherwise be directed to a child Box is + // directed to this Box. + SetPropagateEvents (bool) + // SetGap sets the gap between child Objects. + SetGap (image.Point) + // Add appends a child Object. + Add (Object) + // Delete removes a child Object, if it is a child of this Box. + Delete (Object) + // Insert inserts a child Object before a specified Object. If the + // before Object is nil or is not contained within this Box, the + // inserted Object is appended. + Insert (child Object, before Object) + // Clear removes all child Objects. + Clear () + // Length returns the amount of child objects. + Length () int + // At returns the child Object at the specified index. + At (int) Object + // SetLayout sets the layout of this Box. Child Objects will be + // positioned according to it. + SetLayout (Layout) } // LayoutHints are passed to a layout to tell it how to arrange child boxes. type LayoutHints struct { + // Bounds is the bounding rectangle that children should be placed + // within. Any padding values are already applied. Bounds image.Rectangle + // OverflowX and OverflowY control wether child Boxes may be positioned + // outside of Bounds. OverflowX bool OverflowY bool + // AlignX and AlignY control how child Boxes are aligned horizontally + // and vertically. The effect of this may vary depending on the Layout. AlignX Align AlignY Align + // Gap controls the amount of horizontal and vertical spacing in-between + // child Boxes. Gap image.Point } -// Layout can be given to a ContainerBox to arrange child objects. +// A Layout can be given to a ContainerBox to arrange child objects. type Layout interface { + // MinimumSize returns the minimum width and height of + // LayoutHints.Bounds needed to properly lay out all child Boxes. MinimumSize (LayoutHints, []Box) image.Point + // Arrange arranges child boxes according to the given LayoutHints. Arrange (LayoutHints, []Box) } // Window is an operating system window. It can contain one object. type Window interface { + // SetRoot sets the root child of the window. There can only be one at + // a time, and setting it will remove the current child if there is one. SetRoot (Object) + // SetTitle sets the title of the window. SetTitle (string) - SetIcon (sizes []image.Image) - NewMenu (image.Rectangle) (Window, error) - NewModal (image.Rectangle) (Window, error) + // SetIcon sets the icon of the window. When multiple icon sizes are + // provided, the best fitting one is chosen for display. + SetIcon (... image.Image) + // Widget returns a window representing a smaller iconified form of this + // window. How exactly this window is used depends on the platform. + // Subsequent calls to this method on the same window will return the + // same window object. Widget () (Window, error) + // NewMenu creates a new menu window. This window is undecorated and + // will close once the user clicks outside of it. + NewMenu (image.Rectangle) (Window, error) + // NewModal creates a new modal window that blocks all input to this + // window until it is closed. + NewModal (image.Rectangle) (Window, error) + // Copy copies data to the clipboard. Copy (data.Data) + // Paste reads data from the clipboard. When the data is available or an + // error has occurred, the provided function will be called. Paste (callback func (data.Data, error), accept ...data.Mime) + // Show shows the window. Show () + // Hide hides the window. Hide () + // Close closes the window. Close () + // OnClose specifies a function to be called when the window is closed. OnClose (func ()) event.Cookie } // MainWindow is a top-level operating system window. type MainWindow interface { Window + + // NewChild creates a new window that is semantically a child of this + // window. It does not actually reside within this window, but it may be + // linked to it via some other means. This is intended for things like + // toolboxes and tear-off menus. NewChild (image.Rectangle) (Window, error) }