From bb6de0de48e96193cfba59042bdca9aa1eefb67f Mon Sep 17 00:00:00 2001 From: Pietro Gagliardi Date: Sun, 8 Jun 2014 12:56:04 -0400 Subject: [PATCH] Cleaned up dialog documentation. --- dialog.go | 20 +++++++------------- doc.go | 25 +++++++++++++++++++++++++ todo.md | 2 -- 3 files changed, 32 insertions(+), 15 deletions(-) diff --git a/dialog.go b/dialog.go index 2e96b22..7bda715 100644 --- a/dialog.go +++ b/dialog.go @@ -15,21 +15,13 @@ var dialogWindow *Window // If you pass an empty string for secondaryText, neither additional information nor space for additional information will be shown. // On platforms that allow for the message box window to have a title, os.Args[0] is used. // -// The message box is modal to the entire application: the user cannot interact with any other window until this one is dismissed. -// Whether or not resizing Windows will still be allowed is implementation-defined; if the implementation does allow it, resizes will still work properly. -// Whether or not the message box stays above all other W+indows in the program is also implementation-defined. +// See "On Dialogs" in the package overview for behavioral information. func MsgBox(primaryText string, secondaryText string) { <-dialogWindow.msgBox(primaryText, secondaryText) } -// MsgBox behaves like the package-scope MsgBox function, except the message box is modal to w only. -// Attempts to interact with w will be blocked, but all other Windows in the application can still be used properly. -// The message box will also stay above w. -// Whether w can be resized while the message box is displayed is implementation-defined, but will work properly if allowed. -// If w has not yet been created, MsgBox() panics. -// If w has not been shown yet or is currently hidden, what MsgBox does is implementation-defined. -// -// On return, done will be a channel that is pulsed when the message box is dismissed. +// MsgBox is the Window method version of the package-scope function MsgBox. +// See that function's documentation and "On Dialogs" in the package overview for more information. func (w *Window) MsgBox(primaryText string, secondaryText string) (done chan struct{}) { if !w.created { panic("parent window passed to Window.MsgBox() before it was created") @@ -39,12 +31,14 @@ func (w *Window) MsgBox(primaryText string, secondaryText string) (done chan str // MsgBoxError displays a message box to the user with just an OK button and an icon indicating an error. // Otherwise, it behaves like MsgBox. +// +// See "On Dialogs" in the package overview for more information. func MsgBoxError(primaryText string, secondaryText string) { <-dialogWindow.msgBoxError(primaryText, secondaryText) } -// MsgBoxError displays a message box to the user with just an OK button and an icon indicating an error. -// Otherwise, it behaves like Window.MsgBox. +// MsgBoxError is the Window method version of the package-scope function MsgBoxError. +// See that function's documentation and "On Dialogs" in the package overview for more information. func (w *Window) MsgBoxError(primaryText string, secondaryText string) (done chan struct{}) { if !w.created { panic("parent window passed to MsgBoxError() before it was created") diff --git a/doc.go b/doc.go index 80146e9..3422f48 100644 --- a/doc.go +++ b/doc.go @@ -41,5 +41,30 @@ Here is a simple, complete program that asks the user for their name and greets panic(err) } } + +On Dialogs + +The following functions provide dialogs. They exist both in package scope and as methods on Window. + + MsgBox() + MsgBoxError() + +Dialogs opened by using the package-scope functions are modal to the entire application: the user cannot interact with any other window until they are dismissed. +Whether or not resizing Windows will still be allowed is implementation-defined; if the implementation does allow it, resizes will still work properly. +Whether or not the dialog box stays above all other Windows in the program is also implementation-defined. + +Dialogs opened by using the Window methods are modal to the receiver Window only. +Attempts to interact with the receiver Window will be blocked, but all other Windows in the application can still be used properly. +The dialog box will also stay above the receiver Window. +Whether the receiver Window can be resized while the dialog box is displayed is implementation-defined, but will work properly if allowed. +If the receiver Window has not yet been created, the methods panic. +If the receiver Window has not been shown yet or is currently hidden, what the methods do is implementation-defined. + +The return type also differs between the two types of functions. +Both ultimately either yield a signal that the dialog has been dismissed or a code specifying what the user decided to do with the dialog (if it has multiple choices). +The package-scope functions wait for the dialog box to be dismissed and merely return the code (or nothing if no code is needed). +The Window methods return immediately with a channel that will eventually receive either the signal or the return code. +Package ui does not close these channels, nor does it send multiple values on the same channel. + */ package ui diff --git a/todo.md b/todo.md index e6e60bc..4c7e196 100644 --- a/todo.md +++ b/todo.md @@ -20,7 +20,5 @@ UNIX: - figure out why Page Up/Page Down does tab stops ALL PLATFORMS: -- explain that if a local and global dialog are both opened at once, whetehr or not the local dialog is modal is system-defined (but the window it is local to will still be properly disabled once dismissed) - - will require moving dialog behavior to the package overview - make sure MouseEvent's documentation has dragging described correctly (both Windows and GTK+ do) - make all widths and heights parameters in constructors in the same place (or drop the ones in Window entirely?)