diff --git a/collects/framework/gui-utils.ss b/collects/framework/gui-utils.ss index 0828c14f39..81d883acf1 100644 --- a/collects/framework/gui-utils.ss +++ b/collects/framework/gui-utils.ss @@ -301,9 +301,9 @@ (λ (str) ((string-length str) . <= . size)))]) @{Constructs a string whose size is less - than @scheme[size] by trimming the @scheme[str] - and inserting an ellispses into it.}) - + than @scheme[size] by trimming the @scheme[str] + and inserting an ellispses into it.}) + (proc-doc gui-utils:quote-literal-label (->d ([str string?]) @@ -312,9 +312,9 @@ (lambda (str) ((string-length str) . <= . 200)))]) @{Constructs a string whose ampersand characters are - escaped; the label is also trimmed to <= 200 - characters.}) - + escaped; the label is also trimmed to <= 200 + characters.}) + (proc-doc gui-utils:format-literal-label (->d ([str string?]) @@ -324,19 +324,19 @@ (lambda (str) ((string-length str) . <= . 200)))]) @{Formats a string whose ampersand characters are - escaped; the label is also trimmed to <= 200 - characters.}) - + mk-escaped; the label is also trimmed to <= 200 + mk-characters.}) + (proc-doc/names gui-utils:cancel-on-right? (-> boolean?) () @{Returns @scheme[#t] if cancel should be on the right-hand side (or below) - in a dialog and @scheme[#f] otherwise. - - Just returns what @scheme[system-position-ok-before-cancel?] does. - - See also @scheme[gui-utils:ok/cancel-buttons].}) + in a dialog and @scheme[#f] otherwise. + + Just returns what @scheme[system-position-ok-before-cancel?] does. + + See also @scheme[gui-utils:ok/cancel-buttons].}) (proc-doc/names gui-utils:ok/cancel-buttons (->* ((is-a?/c area-container<%>) @@ -352,24 +352,24 @@ ((confirm-label (string-constant ok)) (cancel-label (string-constant cancel)))) @{Adds an Ok and a cancel button to a panel, changing the order - to suit the platform. Under Mac OS X and unix, the confirmation action - is on the right (or bottom) and under Windows, the canceling action is on the - right (or bottom). - The confirmation action button has the @scheme['(border)] style. - The buttons are also sized to be the same width. - - The first result is be the OK button and the second is - the cancel button. - - See also @scheme[gui-utils:cancel-on-right?].}) + to suit the platform. Under Mac OS X and unix, the confirmation action + is on the right (or bottom) and under Windows, the canceling action is on + the right (or bottom). + The confirmation action button has the @scheme['(border)] style. + The buttons are also sized to be the same width. + + The first result is be the OK button and the second is + the cancel button. + + See also @scheme[gui-utils:cancel-on-right?].}) (proc-doc/names gui-utils:next-untitled-name (-> string?) () @{Returns a name for the next opened untitled frame. The first - name is ``Untitled'', the second is ``Untitled 2'', - the third is ``Untitled 3'', and so forth.}) + name is ``Untitled'', the second is ``Untitled 2'', + the third is ``Untitled 3'', and so forth.}) (proc-doc/names gui-utils:cursor-delay (case-> @@ -377,17 +377,17 @@ (real? . -> . void?)) (() (new-delay)) @{This function is @italic{not} a parameter. - Instead, the state is just stored in the closure. - - The first case in the case lambda - returns the current delay in seconds before a watch cursor is shown, - when either @scheme[gui-utils:local-busy-cursor] or - @scheme[gui-utils:show-busy-cursor] is called. - - The second case in the case lambda - Sets the delay, in seconds, before a watch cursor is shown, when - either @scheme[gui-utils:local-busy-cursor] or - @scheme[gui-utils:show-busy-cursor] is called.}) + Instead, the state is just stored in the closure. + + The first case in the case lambda + returns the current delay in seconds before a watch cursor is shown, + when either @scheme[gui-utils:local-busy-cursor] or + @scheme[gui-utils:show-busy-cursor] is called. + + The second case in the case lambda + Sets the delay, in seconds, before a watch cursor is shown, when + either @scheme[gui-utils:local-busy-cursor] or + @scheme[gui-utils:show-busy-cursor] is called.}) (proc-doc/names gui-utils:show-busy-cursor (->* ((-> any/c)) @@ -396,11 +396,11 @@ ((thunk) ((delay (gui-utils:cursor-delay)))) @{Evaluates @scheme[(thunk)] with a watch cursor. The argument - @scheme[delay] specifies the amount of time before the watch cursor is - opened. Use @scheme[gui-utils:cursor-delay] to set this value - to all calls. - - This function returns the result of @scheme[thunk].}) + @scheme[delay] specifies the amount of time before the watch cursor is + opened. Use @scheme[gui-utils:cursor-delay] to set this value + to all calls. + + This function returns the result of @scheme[thunk].}) (proc-doc/names gui-utils:delay-action (real? @@ -410,25 +410,24 @@ (-> void?)) (delay-time open close) @{Use this function to delay an action for some period of time. It also - supports cancelling the action before the time period elapses. For - example, if you want to display a watch cursor, but you only want it - to appear after 2 seconds and the action may or may not take more than - two seconds, use this pattern: - - @schemeblock[ - (let ([close-down - (gui-utils:delay-action - 2 - (λ () .. init watch cursor ...) - (λ () .. close watch cursor ...))]) - ;; .. do action ... - (close-down))] - - Creates a thread that waits @scheme[delay-time]. After @scheme[delay-time] - has elapsed, if the result thunk has @italic{not} been called, call - @scheme[open]. Then, when the result thunk is called, call - @scheme[close]. The function @scheme[close] will only be called if - @scheme[open] has been called.}) + supports cancelling the action before the time period elapses. For + example, if you want to display a watch cursor, but you only want it + to appear after 2 seconds and the action may or may not take more than + two seconds, use this pattern: + + @schemeblock[(let ([close-down + (gui-utils:delay-action + 2 + (λ () .. init watch cursor ...) + (λ () .. close watch cursor ...))]) + ;; .. do action ... + (close-down))] + + Creates a thread that waits @scheme[delay-time]. After @scheme[delay-time] + has elapsed, if the result thunk has @italic{not} been called, call + @scheme[open]. Then, when the result thunk is called, call + @scheme[close]. The function @scheme[close] will only be called if + @scheme[open] has been called.}) (proc-doc/names gui-utils:local-busy-cursor @@ -440,13 +439,12 @@ ((window thunk) ((delay (gui-utils:cursor-delay)))) @{Evaluates @scheme[(thunk)] with a watch cursor in @scheme[window]. If - @scheme[window] is @scheme[#f], the watch cursor is turned on globally. The - argument @scheme[delay] specifies the amount of time before the watch - cursor is opened. Use - @scheme[gui-utils:cursor-delay] - to set this value for all uses of this function. - - The result of this function is the result of @scheme[thunk].}) + @scheme[window] is @scheme[#f], the watch cursor is turned on globally. + The argument @scheme[delay] specifies the amount of time before the watch + cursor is opened. Use @scheme[gui-utils:cursor-delay] + to set this value for all uses of this function. + + The result of this function is the result of @scheme[thunk].}) (proc-doc/names gui-utils:unsaved-warning @@ -465,21 +463,21 @@ (cancel? #t))) @{This displays a dialog that warns the user of a unsaved file. - - The string, @scheme[action], indicates what action is about to - take place, without saving. For example, if the application - is about to close a file, a good action is @scheme["Close" "Anyway"]. - The result symbol indicates the user's choice. If - @scheme[can-save-now?] is @scheme[#f], this function does not - give the user the ``Save'' option and thus will not return - @scheme['save]. - - If @scheme[cancel?] is @scheme[#t] there is a cancel button - in the dialog and the result may be @scheme['cancel]. If it - is @scheme[#f], then there is no cancel button, and @scheme['cancel] - will not be the result of the function. - - }) + + The string, @scheme[action], indicates what action is about to + take place, without saving. For example, if the application + is about to close a file, a good action is @scheme["Close" "Anyway"]. + The result symbol indicates the user's choice. If + @scheme[can-save-now?] is @scheme[#f], this function does not + give the user the ``Save'' option and thus will not return + @scheme['save]. + + If @scheme[cancel?] is @scheme[#t] there is a cancel button + in the dialog and the result may be @scheme['cancel]. If it + is @scheme[#f], then there is no cancel button, and @scheme['cancel] + will not be the result of the function. + + }) (proc-doc/names gui-utils:get-choice @@ -502,37 +500,37 @@ (checkbox-proc #f) (checkbox-label (string-constant dont-ask-again)))) - @{Opens a dialog that presents a binary choice to the user. The user is forced - to choose between these two options, ie cancelling or closing the dialog - opens a message box asking the user to actually choose one of the two options. - - The dialog will contain the string @scheme[message] and two buttons, - labeled with the @scheme[true-choice] and the @scheme[false-choice]. If the - user clicks on @scheme[true-choice] @scheme[#t] is returned. If the user - clicks on @scheme[false-choice], @scheme[#f] is returned. - - The argument @scheme[default-result] determines how closing the window is - treated. If the argument is @scheme['disallow-close], closing the window - is not allowed. If it is anything else, that value is returned when - the user closes the window. - - If - @scheme[gui-utils:cancel-on-right?] - returns @scheme[#t], the false choice is on the right. - Otherwise, the true choice is on the right. - - The @scheme[style] parameter is (eventually) passed to - @scheme[message] - as an icon in the dialog. - - If @scheme[checkbox-proc] is given, it should be a procedure that behaves - like a parameter for getting/setting a boolean value. The intention for - this value is that it can be used to disable the dialog. When it is - given, a checkbox will appear with a @scheme[checkbox-label] label - (defaults to the @scheme[dont-ask-again] string constant), and that - checkbox value will be sent to the @scheme[checkbox-proc] when the dialog - is closed. Note that the dialog will always pop-up --- it is the - caller's responsibility to avoid the dialog if not needed.}) + @{Opens a dialog that presents a binary choice to the user. The user is + forced to choose between these two options, ie cancelling or closing the + dialog opens a message box asking the user to actually choose one of the + two options. + + The dialog will contain the string @scheme[message] and two buttons, + labeled with the @scheme[true-choice] and the @scheme[false-choice]. If the + user clicks on @scheme[true-choice] @scheme[#t] is returned. If the user + clicks on @scheme[false-choice], @scheme[#f] is returned. + + The argument @scheme[default-result] determines how closing the window is + treated. If the argument is @scheme['disallow-close], closing the window + is not allowed. If it is anything else, that value is returned when + the user closes the window. + + If @scheme[gui-utils:cancel-on-right?] + returns @scheme[#t], the false choice is on the right. + Otherwise, the true choice is on the right. + + The @scheme[style] parameter is (eventually) passed to + @scheme[message] + as an icon in the dialog. + + If @scheme[checkbox-proc] is given, it should be a procedure that behaves + like a parameter for getting/setting a boolean value. The intention for + this value is that it can be used to disable the dialog. When it is + given, a checkbox will appear with a @scheme[checkbox-label] label + (defaults to the @scheme[dont-ask-again] string constant), and that + checkbox value will be sent to the @scheme[checkbox-proc] when the dialog + is closed. Note that the dialog will always pop-up --- it is the + caller's responsibility to avoid the dialog if not needed.}) (proc-doc/names gui-utils:get-clicked-clickback-delta @@ -542,14 +540,14 @@ (() ((white-on-black? #f))) @{This delta is designed for use with - @method[text set-clickback]. - Use it as one of the @scheme[style-delta%] argument to - @method[text% set-clickback]. - - If @scheme[white-on-black?] is true, the function returns - a delta suitable for use on a black background. - - See also @scheme[gui-utils:get-clickback-delta].}) + @method[text set-clickback]. + Use it as one of the @scheme[style-delta%] argument to + @method[text% set-clickback]. + + If @scheme[white-on-black?] is true, the function returns + a delta suitable for use on a black background. + + See also @scheme[gui-utils:get-clickback-delta].}) (proc-doc/names gui-utils:get-clickback-delta @@ -558,14 +556,12 @@ (is-a?/c style-delta%)) (() ((white-on-black? #f))) - @{This delta is designed for use with - @method[text% set-clickback]. - Use the result of this function as the style - for the region - text where the clickback is set. - - If @scheme[white-on-black?] is true, the function returns - a delta suitable for use on a black background. - - See also - @scheme[gui-utils:get-clicked-clickback-delta].})) + @{This delta is designed for use with @method[text% set-clickback]. + Use the result of this function as the style + for the region text where the clickback is set. + + If @scheme[white-on-black?] is true, the function returns + a delta suitable for use on a black background. + + See also + @scheme[gui-utils:get-clicked-clickback-delta].}))