main.rkt
1 #lang at-exp racket/base 2 3 (require racket/contract/base 4 racket/unit 5 racket/class 6 racket/gui/base 7 racket/set 8 mred/mred-unit 9 framework/framework-unit 10 framework/private/sig 11 (for-syntax scheme/base) 12 scribble/srcdoc 13 (for-syntax "private/scheme.rkt")) 14 15 ;; these next two lines do a little dance to make the 16 ;; require/doc setup work out properly 17 (require (prefix-in :: framework/private/focus-table)) 18 (define frame:lookup-focus-table ::frame:lookup-focus-table) 19 20 (require framework/preferences 21 framework/test 22 framework/gui-utils 23 framework/decorated-editor-snip 24 framework/private/decorated-editor-snip) 25 26 (provide (all-from-out framework/preferences 27 framework/test 28 framework/gui-utils 29 framework/decorated-editor-snip 30 framework/private/decorated-editor-snip)) 31 32 (require (for-doc racket/base scribble/manual framework/private/mapdesc 33 setup/getinfo racket/pretty string-constants)) 34 35 (provide-signature-elements 36 (prefix application: framework:application-class^) 37 (prefix version: framework:version-class^) 38 (prefix color-model: framework:color-model-class^) 39 (prefix mode: framework:mode-class^) 40 (prefix exit: framework:exit-class^) 41 (prefix menu: framework:menu-class^) 42 (prefix preferences: framework:preferences-class^) 43 (prefix number-snip: framework:number-snip-class^) 44 (prefix autosave: framework:autosave-class^) 45 (prefix path-utils: framework:path-utils-class^) 46 (prefix icon: framework:icon-class^) 47 (prefix keymap: framework:keymap-class^) 48 (prefix editor: framework:editor-class^) 49 (prefix pasteboard: framework:pasteboard-class^) 50 (prefix text: framework:text-class^) 51 (prefix color: framework:color-class^) 52 (prefix color-prefs: framework:color-prefs-class^) 53 (prefix comment-box: framework:comment-box-class^) 54 (prefix finder: framework:finder-class^) 55 (prefix group: framework:group-class^) 56 (prefix canvas: framework:canvas-class^) 57 (prefix panel: framework:panel-class^) 58 (prefix frame: framework:frame-class^) 59 (prefix handler: framework:handler-class^) 60 (prefix racket: framework:racket-class^) 61 (prefix main: framework:main-class^)) 62 63 (define-values/invoke-unit/infer 64 (export framework^) 65 (link standard-mred@ framework@)) 66 67 (provide 68 69 (proc-doc 70 color:get-parenthesis-colors-table 71 (-> (listof (list/c symbol? string? (vectorof (is-a?/c color%)) (or/c 'low 'high)))) 72 @{Returns a table of colors that get used for parenthesis highlighting. 73 Each entry in the table consists of a symbolic name, a name to show 74 in a GUI, the color to use, and the @racket[_priority] argument to 75 pass to @racket[text:basic<%> highlight-range] when highlighting the parens. 76 Generally the priority should be @racket['low] if the color is solid 77 (α=1) but can be @racket['high] if the α component is small. 78 79 When an entry in the table has multiple colors, they are used to show the nesting 80 structure in the parentheses.}) 81 82 (thing-doc 83 color:misspelled-text-color-style-name 84 string? 85 @{The name of the style used to color misspelled words. See also 86 @method[color:text<%> get-spell-check-strings].}) 87 88 (proc-doc/names 89 text:range? (-> any/c boolean?) (arg) 90 @{Determines if @racket[arg] is an instance of the @tt{range} struct.}) 91 92 (proc-doc/names 93 text:range-start 94 (-> text:range? exact-nonnegative-integer?) 95 (range) 96 @{Returns the start position of the range.}) 97 98 (proc-doc/names 99 text:range-end 100 (-> text:range? exact-nonnegative-integer?) 101 (range) 102 @{Returns the end position of the range.}) 103 104 (proc-doc/names 105 text:range-caret-space? 106 (-> text:range? boolean?) 107 (range) 108 @{Returns a boolean indicating where the caret-space in the range goes. 109 See also @method[text:basic<%> highlight-range].}) 110 111 (proc-doc/names 112 text:range-style 113 (-> text:range? (or/c 'rectangle 'hollow-ellipse 'ellipse 'dot)) 114 (range) 115 @{Returns the style of the range. 116 See also @method[text:basic<%> highlight-range].}) 117 118 (proc-doc/names 119 text:range-color 120 (-> text:range? (or/c string? (is-a?/c color%))) 121 (range) 122 @{Returns the color of the highlighted range.}) 123 124 (parameter-doc 125 text:autocomplete-append-after 126 (parameter/c string?) 127 suffix 128 @{A string that is inserted after a completion is inserted by a 129 @racket[text:autocomplete] instance. 130 131 Defaults to @racket[""].}) 132 133 (parameter-doc 134 text:autocomplete-limit 135 (parameter/c (and/c integer? exact? positive?)) 136 count 137 @{Controls the number of completions visible at a time in the menu produced 138 by @racket[text:autocomplete] instances. 139 140 Defaults to 15.}) 141 142 (proc-doc/names 143 text:get-completions/manuals 144 (-> (or/c false/c (listof symbol?)) (listof string?)) 145 (manuals) 146 @{Returns the list of keywords for the manuals from @racket[manuals] by 147 extracting all of the documented exports of the manuals. The symbols are 148 meant to be module paths, e.g., the quoted form of the argument to 149 @racket[require]. 150 151 If @racket[manuals] is false, then all of the documented names are used.}) 152 153 (proc-doc/names 154 text:lookup-port-name 155 (-> symbol? (or/c (is-a?/c editor:basic<%>) false/c)) 156 (manuals) 157 @{Returns the editor instance whose port-name matches the given symbol. 158 If no editor can be found, then returns @racket[false].}) 159 160 (proc-doc/names 161 text:make-snip-special 162 (-> (is-a?/c snip%) text:snip-special?) 163 (snip) 164 @{Returns a @racket[snip-special] to be used as a 165 @tech[#:doc '(lib "scribblings/reference/reference.scrbl")]{special} 166 with the ports in @racket[text:ports<%>]. 167 168 When a snip is sent as a special, if it has a @racket[snip-class%] 169 from a different @tech[#:doc '(lib "scribblings/gui/gui.scrbl")]{eventspace}, 170 it may not work properly 171 in the @racket[text%] object connected to the ports in a @racket[text:port<%>] 172 object. This function, when it is called, constructs the bytes 173 corresponding to the result of using the @racket[snip]'s 174 @method[snip% write] method and saves them in its result. Then, 175 when the result is used as a special, the snip will rebuild from 176 the bytes, but now using the @racket[snip-class%] from the 177 @tech[#:doc '(lib "scribblings/gui/gui.scrbl")]{eventspace} 178 where the @racket[text:ports<%>] operates.}) 179 180 (proc-doc/names 181 text:snip-special? 182 (-> any/c boolean?) 183 (v) 184 @{Recognizes the result of @racket[text:make-snip-special].}) 185 186 (proc-doc/names 187 text:send-snip-to-port 188 (-> (is-a?/c snip%) output-port? void?) 189 (snip port) 190 @{Sends @racket[snip] to @racket[port] by using @racket[text:make-snip-special], 191 handling a few special cases for performance and backwards compatibility 192 reasons.}) 193 194 (proc-doc/names 195 number-snip:make-repeating-decimal-snip 196 (-> real? boolean? number-snip:is-number-snip?) 197 (num show-prefix?) 198 @{Makes a @tech{number snip} that shows the decimal expansion for @racket[number]. 199 The boolean indicates if a @litchar{#e} prefix appears on the number. 200 201 See also @racket[number-snip:make-fraction-snip].}) 202 203 (proc-doc/names 204 number-snip:make-fraction-snip 205 (-> real? boolean? number-snip:is-number-snip?) 206 (num show-prefix-in-decimal-view?) 207 @{Makes a @tech{number snip} that shows a fractional view of @racket[number]. 208 The boolean indicates if a @litchar{#e} prefix appears on the number, when 209 shown in the decimal state. 210 211 See also @racket[number-snip:make-repeating-decimal-snip].}) 212 213 (proc-doc/names 214 number-snip:is-number-snip? 215 (-> any/c boolean?) 216 (v) 217 @{Determines if @racket[v] is a @deftech{number snip}, i.e., created 218 by @racket[number-snip:make-fraction-snip] 219 or @racket[number-snip:make-repeating-decimal-snip]. 220 221 All values that answer @racket[#t] to this predicate are also @racket[snip%]s.}) 222 223 (proc-doc/names 224 number-snip:get-number 225 (-> number-snip:is-number-snip? real?) 226 (ns) 227 @{Returns the number that this @tech{number snip} displays.}) 228 229 (thing-doc 230 comment-box:snipclass 231 (is-a?/c snip-class%) 232 @{The @racket[snip-class%] object used by @racket[comment-box:snip%].}) 233 234 (proc-doc/names 235 version:add-spec 236 (any/c any/c . -> . void?) 237 (spec revision) 238 @{The two values are appended to the version string. @racket[write] is used 239 to transform them to strings. For example: 240 241 @racket[(version:add-spec 's 1)] 242 243 in version 205 will make the version string be @litchar{205s1}. The 244 symbols @racket['f] and @racket['d] were used internally for framework and 245 drscheme revisions in the past.}) 246 247 (proc-doc/names 248 version:version 249 (-> string?) 250 () 251 @{This function returns a string describing the version of this application. 252 See also @racket[version:add-spec].}) 253 254 (parameter-doc 255 application:current-app-name 256 (parameter/c string?) 257 name 258 @{This is a parameter specifying the name of the current application. It is 259 used in the help menu (see @racket[frame:standard-menus%]) and in frame 260 titles (see @racket[frame:editor%]). The first case in the case-lambda 261 returns the current name, and the second case in the case-lambda sets the 262 name of the application to @racket[name].}) 263 264 (proc-doc/names 265 preferences:put-preferences/gui 266 (-> (listof symbol?) 267 (listof any/c) 268 any) 269 (name-list val-list) 270 @{Like @racket[put-preferences], but has more sophisticated error handling. 271 In particular, when it fails to grab a lock, it 272 @itemize[ 273 @item{waits for three consecutive failures before informing the user} 274 @item{gives the user the opportunity to ``steal'' the lockfile after the 275 third failure, and} 276 @item{when lock failures occur, it remembers what its arguments were and if 277 any preference save eventually succeeds, all of the past failures 278 are also written at that point.}] 279 280 In addition when an error is raised trying to save a preference to the preference 281 file, @racket[preferences:put-preferences/gui] logs the error using @racket[log-warning], 282 instead of raising an exception. 283 }) 284 285 (proc-doc/names 286 preferences:get-preference/gui 287 (->* (symbol?) 288 ((-> void?)) 289 any/c) 290 ((sym) 291 ((default (λ () (error 'get-preference/gui "unknown pref ~s" sym))))) 292 @{Like @racket[get-preference], but has more sophisticated error handling. 293 In particular, it passes a @racket[#:timeout-lock-there] argument that 294 informs the user that the preferences file is locked (and offers the alternative 295 of not showing the message again).}) 296 297 298 (proc-doc/names 299 preferences:add-panel 300 (-> (or/c string? (cons/c string? (listof string?))) 301 (->i ([parent (is-a?/c area-container-window<%>)]) 302 () 303 [_ (parent) 304 (let ([old-children (send parent get-children)]) 305 (and/c (is-a?/c area-container-window<%>) 306 (λ (child) 307 (andmap eq? 308 (append old-children (list child)) 309 (send parent get-children)))))]) 310 void?) 311 (labels f) 312 @{@racket[preferences:add-preference-panel] adds the result of @racket[f] 313 with name @racket[labels] to the preferences dialog box. 314 315 The labels determine where this preference panel is placed in the dialog. 316 If the list is just one string, the preferences panel is placed at the top 317 level of the dialog. If there are more strings, a hierarchy of nested 318 panels is created and the new panel is added at the end. If multiple calls 319 to @racket[preferences:add-preference-panel] pass the same prefix of 320 strings, those panels are placed in the same children. 321 322 When the preference dialog is opened for the first time, the function 323 @racket[f] is called with a panel, and @racket[f] is expected to add a new 324 child panel to it and add whatever preferences configuration controls it 325 wants to that panel. Then, @racket[f]'s should return the panel it added.}) 326 327 (proc-doc/names 328 preferences:add-editor-checkbox-panel 329 (-> void?) 330 () 331 @{Adds a preferences panel for configuring options related to editing.}) 332 333 (proc-doc/names 334 preferences:add-general-checkbox-panel 335 (-> void?) 336 () 337 @{Adds a catch-all preferences panel for options.}) 338 339 (proc-doc/names 340 preferences:add-warnings-checkbox-panel 341 (-> void?) 342 () 343 @{Adds a preferences panel for configuring options relating to warnings.}) 344 345 (proc-doc/names 346 preferences:add-scheme-checkbox-panel 347 (-> void?) 348 () 349 @{Adds a preferences panel for configuring options related to Racket.}) 350 351 (proc-doc/names 352 preferences:add-to-warnings-checkbox-panel 353 (((is-a?/c vertical-panel%) . -> . void?) . -> . void?) 354 (proc) 355 @{Saves @racket[proc] until the preferences panel is created, when it is 356 called with the Misc. panel to add new children to the panel.}) 357 358 (proc-doc/names 359 preferences:add-to-scheme-checkbox-panel 360 (((is-a?/c vertical-panel%) . -> . void?) . -> . void?) 361 (proc) 362 @{Saves @racket[proc] until the preferences panel is created, when it is 363 called with the Racket preferences panel to add new children to the 364 panel.}) 365 366 (proc-doc/names 367 preferences:add-to-editor-checkbox-panel 368 (((is-a?/c vertical-panel%) . -> . void?) . -> . void?) 369 (proc) 370 @{Saves @racket[proc] until the preferences panel is created, when it is 371 called with the editor preferences panel to add new children to the 372 panel.}) 373 374 (proc-doc/names 375 preferences:add-to-general-checkbox-panel 376 (((is-a?/c vertical-panel%) . -> . void?) . -> . void?) 377 (proc) 378 @{Saves @racket[proc] until the preferences panel is created, when it is 379 called with the general preferences panel to add new children to the 380 panel.}) 381 382 (proc-doc/names 383 preferences:add-font-panel 384 (-> void?) 385 () 386 @{Adds a font selection preferences panel to the preferences dialog.}) 387 388 (proc-doc/names 389 preferences:show-dialog 390 (-> void?) 391 () 392 @{Shows the preferences dialog.}) 393 394 (proc-doc/names 395 preferences:hide-dialog 396 (-> void?) 397 () 398 @{Hides the preferences dialog.}) 399 400 (proc-doc/names 401 preferences:add-on-close-dialog-callback 402 ((-> void?) . -> . void?) 403 (cb) 404 @{Registers @racket[cb]. Next time the user clicks the OK button the 405 preferences dialog, all of the @racket[cb] functions are called, assuming 406 that each of the callbacks passed to 407 @racket[preferences:add-can-close-dialog-callback] succeed.}) 408 409 (proc-doc/names 410 preferences:add-can-close-dialog-callback 411 ((-> boolean?) . -> . void?) 412 (cb) 413 @{Registers @racket[cb]. Next time the user clicks the OK button the 414 preferences dialog, all of the @racket[cb] functions are called. If any of 415 them return @racket[#f], the dialog is not closed. 416 417 See also @racket[preferences:add-on-close-dialog-callback].}) 418 419 (proc-doc/names 420 preferences:add-check 421 (->* ((is-a?/c area-container<%>) symbol? string?) 422 ((-> boolean? any/c) 423 (-> any/c boolean?)) 424 void?) 425 ((parent pref-key label) ((from-boolean values) (to-boolean values))) 426 @{Adds a @racket[radio-box%] object (with @racket[label] as its label) 427 to @racket[parent] that, when checked 428 adjusts the preference with the key @racket[pref-key]. 429 430 The @racket[to-boolean] and @racket[from-boolean] functions 431 are used to convert from the preferences value to a booleans 432 when checking/unchecking the @racket[radio-box%] object. 433 The defaults amount to treating the preference as a boolean such 434 that checking the @racket[radio-box%] sets the preference to 435 @racket[#t] and unchecking it sets the preference to @racket[#f]. 436 }) 437 438 (proc-doc/names 439 autosave:register 440 ((and/c (is-a?/c autosave:autosavable<%>) 441 (is-a?/c editor<%>)) 442 . -> . 443 void?) 444 (obj) 445 @{Adds @racket[obj] to the list of objects to be autosaved. When it is time 446 to autosave, the @racket[do-autosave] method of the object is called. This 447 method is responsible for performing the autosave. 448 449 There is no need to de-register an object because the autosaver keeps a 450 @tech[#:doc '(lib "scribblings/reference/reference.scrbl")]{weak reference} 451 to the object; i.e., the autosaver does not keep an object 452 from garbage collection.}) 453 454 (thing-doc 455 autosave:current-toc-path 456 (make-parameter path?) 457 @{The path to the a table-of-contents file for the autosave files. 458 459 The parameter is inspected only when the autosave timer expires, which will not happen until 460 after the first call to @racket[autosave:register]}) 461 462 (thing-doc 463 autosave:toc-path 464 path? 465 @{The default value of the parameter @racket[autosave:current-toc-path], and the 466 path to the autosave that DrRacket uses.}) 467 468 (proc-doc/names 469 autosave:restore-autosave-files/gui 470 (-> void?) 471 () 472 @{Opens a GUI to ask the user about recovering any autosave files left around 473 from crashes and things. 474 475 This function doesn't return until the user has finished restoring the 476 autosave files. (It uses yield to handle events however.)}) 477 478 (proc-doc/names 479 exit:exiting? 480 (-> boolean?) 481 () 482 @{Returns @racket[#t] to indicate that an exit operation is taking place. 483 Does not indicate that the app will actually exit, since the user may 484 cancel the exit. 485 486 See also @racket[exit:insert-on-callback] and 487 @racket[exit:insert-can?-callback].}) 488 489 (proc-doc/names 490 exit:set-exiting 491 (boolean? . -> . void?) 492 (exiting?) 493 @{Sets a flag that affects the result of @racket[exit:exiting?].}) 494 495 (proc-doc/names 496 exit:insert-on-callback 497 ((-> void?) . -> . (-> void?)) 498 (callback) 499 @{Adds a callback to be called when exiting. This callback must not fail. 500 If a callback should stop an exit from happening, use 501 @racket[exit:insert-can?-callback].}) 502 503 (proc-doc/names 504 exit:insert-can?-callback 505 ((-> boolean?) . -> . (-> void?)) 506 (callback) 507 @{Use this function to add a callback that determines if an attempted exit 508 can proceed. This callback should not clean up any state, since another 509 callback may veto the exit. Use @racket[exit:insert-on-callback] for 510 callbacks that clean up state.}) 511 512 (proc-doc/names 513 exit:can-exit? 514 (-> boolean?) 515 () 516 @{Calls the ``can-callbacks'' and returns their results. See 517 @racket[exit:insert-can?-callback] for more information.}) 518 519 (proc-doc/names 520 exit:on-exit 521 (-> void?) 522 () 523 @{Calls the ``on-callbacks''. See @racket[exit:insert-on-callback] for more 524 information.}) 525 526 (proc-doc/names 527 exit:exit 528 (-> any) 529 () 530 @{@racket[exit:exit] performs four actions: 531 @itemize[ 532 @item{sets the result of the @racket[exit:exiting?] function to 533 @racket[#t].} 534 @item{invokes the exit-callbacks, with @racket[exit:can-exit?] if none of 535 the ``can?'' callbacks return @racket[#f],} 536 @item{invokes @racket[exit:on-exit] and then} 537 @item{queues a callback that calls @racket[exit] (a racket procedure) 538 and (if @racket[exit] returns) sets the result of 539 @racket[exit:exiting?] back to @racket[#f].}]}) 540 541 (proc-doc/names 542 exit:user-oks-exit 543 (-> boolean?) 544 () 545 @{Opens a dialog that queries the user about exiting. Returns the user's 546 decision.}) 547 548 (proc-doc/names 549 path-utils:generate-autosave-name 550 (-> (or/c #f path-string? path-for-some-system?) path?) 551 (filename) 552 @{Generates a name for an autosave file from @racket[filename].}) 553 554 (proc-doc/names 555 path-utils:generate-backup-name 556 (path? . -> . path?) 557 (filename) 558 @{Generates a name for an backup file from @racket[filename].}) 559 560 (parameter-doc 561 finder:dialog-parent-parameter 562 (parameter/c (or/c false/c (is-a?/c dialog%) (is-a?/c frame%))) 563 parent 564 @{This parameter determines the parent of the dialogs created by 565 @racket[finder:get-file], @racket[finder:put-file], 566 @racket[finder:common-get-file], @racket[finder:common-put-file], 567 @racket[finder:common-get-file-list], @racket[finder:std-get-file], 568 and @racket[finder:std-put-file].}) 569 570 (parameter-doc 571 finder:default-extension 572 (parameter/c string?) 573 extension 574 @{This parameter controls the default extension for the framework's 575 @racket[finder:put-file] and @racket[finder:get-file] dialog. Its value gets passed as the 576 @racket[_extension] argument to @racket[put-file] and @racket[get-file]. 577 578 Its default value is @racket[""].}) 579 580 (parameter-doc 581 finder:default-filters 582 (parameter/c (listof (list/c string? string?))) 583 filters 584 @{This parameter controls the default filters for the framework's 585 @racket[finder:put-file] dialog. Its value gets passed as the 586 @racket[default-filters] argument to @racket[put-file]. 587 588 Its default value is @racket['(("Any" "*.*"))].}) 589 590 (proc-doc/names 591 finder:common-put-file 592 (->* () 593 (string? 594 (or/c false/c path?) 595 boolean? 596 string? 597 (or/c false/c byte-regexp?) 598 string? 599 (or/c (is-a?/c top-level-window<%>) false/c)) 600 (or/c false/c path?)) 601 (() 602 ((name "Untitled") 603 (directory #f) 604 (replace? #f) 605 (prompt "Select File") 606 (filter #f) 607 (filter-msg "That filename does not have the right form.") 608 (parent (finder:dialog-parent-parameter)))) 609 @{This procedure queries the user for a single filename, using a 610 platform-independent dialog box. Consider using @racket[finder:put-file] 611 instead of this function.}) 612 613 (proc-doc/names 614 finder:common-get-file 615 (->* () 616 ((or/c path? false/c) 617 string? 618 (or/c byte-regexp? false/c) 619 string? 620 (or/c false/c (is-a?/c top-level-window<%>))) 621 (or/c path? false/c)) 622 (() 623 ((directory #f) 624 (prompt "Select File") 625 (filter #f) 626 (filter-msg "That filename does not have the right form.") 627 (parent #f))) 628 @{This procedure queries the user for a single filename, using a 629 platform-independent dialog box. Consider using 630 @racket[finder:get-file] instead of this function.}) 631 632 (proc-doc/names 633 finder:std-put-file 634 (->* () 635 (string? 636 (or/c false/c path?) 637 boolean? 638 string? 639 (or/c false/c byte-regexp?) 640 string? 641 (or/c (is-a?/c top-level-window<%>) false/c)) 642 (or/c false/c path?)) 643 (() 644 ((name "Untitled") 645 (directory #f) 646 (replace? #f) 647 (prompt "Select File") 648 (filter #f) 649 (filter-msg "That filename does not have the right form.") 650 (parent (finder:dialog-parent-parameter)))) 651 @{This procedure queries the user for a single filename, using a 652 platform-dependent dialog box. Consider using @racket[finder:put-file] 653 instead of this function.}) 654 655 (proc-doc/names 656 finder:std-get-file 657 (->* () 658 ((or/c path? false/c) 659 string? 660 (or/c byte-regexp? false/c) 661 string? 662 (or/c false/c (is-a?/c top-level-window<%>))) 663 (or/c path? false/c)) 664 (() 665 ((directory #f) 666 (prompt "Select File") 667 (filter #f) 668 (filter-msg "That filename does not have the right form.") 669 (parent #f))) 670 @{This procedure queries the user for a single filename, using a 671 platform-dependent dialog box. Consider using @racket[finder:get-file] 672 instead of this function.}) 673 674 (proc-doc/names 675 finder:put-file 676 (->* () 677 (string? 678 (or/c false/c path?) 679 boolean? 680 string? 681 (or/c false/c byte-regexp?) 682 string? 683 (or/c (is-a?/c top-level-window<%>) false/c)) 684 (or/c false/c path?)) 685 (() 686 ((name "Untitled") 687 (directory #f) 688 (replace? #f) 689 (prompt "Select File") 690 (filter #f) 691 (filter-msg "That filename does not have the right form.") 692 (parent (finder:dialog-parent-parameter)))) 693 @{Queries the user for a filename. 694 695 If the result of @racket[(preferences:get 'framework:file-dialogs)] is 696 @racket['std] this calls @racket[finder:std-put-file], and if it is 697 @racket['common], @racket[finder:common-put-file] is called.}) 698 699 (proc-doc/names 700 finder:get-file 701 (->* () 702 ((or/c path? false/c) 703 string? 704 (or/c byte-regexp? string? false/c) 705 string? 706 (or/c false/c (is-a?/c top-level-window<%>))) 707 (or/c path? false/c)) 708 (() 709 ((directory #f) 710 (prompt "Select File") 711 (filter #f) 712 (filter-msg "That filename does not have the right form.") 713 (parent #f))) 714 @{Queries the user for a filename. 715 716 If the result of @racket[(preferences:get 'framework:file-dialogs)] is 717 @racket['std] this calls @racket[finder:std-get-file], and if it is 718 @racket['common], @racket[finder:common-get-file] is called.}) 719 720 (proc-doc/names 721 frame:setup-size-pref 722 (->* (symbol? number? number?) 723 (#:maximized? 724 boolean? 725 #:position-preferences 726 (or/c #f symbol?)) 727 void?) 728 ((size-pref-sym width height) 729 ((maximized? #f) 730 (position-preferences-sym #f))) 731 @{Initializes a preference for the @racket[frame:size-pref] mixin. 732 733 The first argument should be the preferences symbol, and the second and 734 third should be the default width and height, respectively. If the 735 window should be maximized by default, pass @racket[#t] for the 736 @racket[maximized?] argument. 737 738 If @racket[position-preferences-sym] is passed, then that symbol will be 739 used to track the position of the window. 740 }) 741 742 (proc-doc/names 743 frame:add-snip-menu-items 744 (->* ((is-a?/c menu%) (subclass?/c menu-item%)) 745 ((-> (is-a?/c menu-item%) void?)) 746 void?) 747 ((menu menu-item%) 748 ((func void))) 749 @{Inserts three menu items into @racket[menu], one that inserts a text box, 750 one that inserts a pasteboard box, and one that inserts an image into the 751 currently focused editor (if there is one). Uses @racket[menu-item%] as 752 the class for the menu items. 753 754 Calls @racket[func] right after inserting each menu item.}) 755 756 (proc-doc/names 757 frame:reorder-menus 758 (-> (is-a?/c frame%) void?) 759 (frame) 760 @{Re-orders the menus in a frame. It moves the ``File'' and ``Edit'' menus 761 to the front of the menubar and moves the ``Windows'' and ``Help'' menus to 762 the end of the menubar. 763 764 This is useful in conjunction with the frame classes. After instantiating 765 the class and adding ones own menus, the menus will be mis-ordered. This 766 function fixes them up.}) 767 768 (proc-doc/names 769 frame:remove-empty-menus 770 ((is-a?/c frame%) . -> . void?) 771 (frame) 772 @{Removes empty menus in a frame.}) 773 774 (parameter-doc 775 frame:current-icon 776 (parameter/c (or/c #f 777 (is-a?/c bitmap%) 778 (cons/c (is-a?/c bitmap%) 779 (is-a?/c bitmap%)))) 780 icon-spec 781 @{The value of this parameter is used by the initialization code of 782 @racket[frame:basic-mixin]. 783 @itemize[ 784 @item{If it is @racket[#f], then its value is ignored.} 785 @item{If it is a @racket[bitmap%], then the @method[top-level-window<%> set-icon] is 786 called with the bitmap, the result of invoking the 787 @racket[bitmap% get-loaded-mask] method, and @racket['both].} 788 @item{If it is a pair of bitmaps, then the @method[top-level-window<%> set-icon] 789 method is invoked twice, once with each bitmap in the pair. The 790 first bitmap is passed (along with the result of its 791 @racket[bitmap% get-loaded-mask]) and @racket['small], and then the 792 second bitmap is passed (also along with the result of its 793 @racket[bitmap% get-loaded-mask]) and @racket['large].}] 794 795 Defaults to @racket[#f].}) 796 797 (proc-doc/names 798 frame:lookup-focus-table 799 (->* () (eventspace?) (listof (is-a?/c frame:focus-table<%>))) 800 (() 801 ((eventspace (current-eventspace)))) 802 @{Returns a list of the frames in @racket[eventspace], where the first element of the list 803 is the frame with the focus. 804 805 The order and contents of the list are maintained by 806 the methods in @racket[frame:focus-table-mixin], meaning that the 807 OS-level callbacks that track the focus of individual frames is 808 ignored. 809 810 See also @racket[test:use-focus-table] and @racket[test:get-active-top-level-window]. 811 812 }) 813 814 (proc-doc/names 815 group:get-the-frame-group 816 (-> (is-a?/c group:%)) 817 () 818 @{This returns the frame group.}) 819 820 (proc-doc/names 821 group:on-close-action 822 (-> void?) 823 () 824 @{See also @racket[group:can-close-check]. 825 826 Call this function from the @method[top-level-window<%> can-close?] 827 callback of a frame in order for the group to properly close the 828 application.}) 829 830 (proc-doc/names 831 group:can-close-check 832 (-> boolean?) 833 () 834 @{See also @racket[group:on-close-action]. 835 836 Call this function from the @method[top-level-window<%> can-close?] 837 callback of a frame in order for the group to properly close the 838 application.}) 839 840 (proc-doc/names 841 group:add-to-windows-menu 842 (-> (-> (is-a?/c menu%) any) any) 843 (proc) 844 @{Procedures passed to this function are called when the @onscreen{Windows} 845 menu is created. Use it to add additional menu items.}) 846 847 (proc-doc/names 848 group:create-windows-menu 849 (-> (is-a?/c menu-item-container<%>) (is-a?/c menu%)) 850 (mb) 851 @{Creates a windows menu, registers it (internally) with 852 the frame group (see @racket[(get-the-frame-group)]), and 853 returns it.}) 854 855 (proc-doc/names 856 handler:handler? 857 (any/c . -> . boolean?) 858 (obj) 859 @{This predicate determines if its input is a handler.}) 860 861 (proc-doc/names 862 handler:handler-name 863 (handler:handler? . -> . string?) 864 (handler) 865 @{Extracts the name from a handler.}) 866 867 (proc-doc/names 868 handler:handler-extension 869 (handler:handler? 870 . -> . (or/c (path? . -> . boolean?) (listof string?))) 871 (handler) 872 @{Extracts the extension from a handler.}) 873 874 (proc-doc/names 875 handler:handler-handler 876 (handler:handler? . -> . (path? . -> . (is-a?/c frame:editor<%>))) 877 (handler) 878 @{Extracts the handler's handling function.}) 879 880 (proc-doc/names 881 handler:insert-format-handler 882 (string? 883 (or/c string? (listof string?) (path? . -> . boolean?)) 884 (path? . -> . (or/c false/c (is-a?/c frame:editor<%>))) 885 . -> . 886 void?) 887 (name pred handler) 888 @{This function inserts a format handler. 889 890 The string, @racket[name] names the format handler for use with 891 @racket[handler:find-named-format-handler]. If @racket[pred] is a string, 892 it is matched with the extension of a filename by 893 @racket[handler:find-format-handler]. If @racket[pred] is a list of 894 strings, they are each matched with the extension of a filename by 895 @racket[handler:find-format-handler]. If it is a function, the filename is 896 applied to the function and the functions result determines if this is the 897 handler to use. 898 899 The most recently added format handler takes precedence over all other 900 format handlers.}) 901 902 (proc-doc/names 903 handler:find-named-format-handler 904 (-> string? (or/c #f (-> path? (is-a?/c frame:editor<%>)))) 905 (name) 906 @{This function selects a format handler. See also 907 @racket[handler:insert-format-handler]. 908 909 It finds a handler based on @racket[name].}) 910 911 (proc-doc/names 912 handler:find-format-handler 913 (-> path? (or/c #f (-> path? (is-a?/c frame:editor<%>)))) 914 (filename) 915 @{This function selects a format handler. See also 916 @racket[handler:insert-format-handler]. 917 918 It finds a handler based on @racket[filename].}) 919 920 (proc-doc/names 921 handler:edit-file 922 (->* ((or/c path? false/c)) 923 ((-> (is-a?/c frame:editor<%>))) 924 (or/c false/c (is-a?/c frame:editor<%>))) 925 ((filename) 926 ((make-default 927 (λ () ((handler:current-create-new-window) filename))))) 928 @{This function invokes the appropriate format handler to open the file (see 929 @racket[handler:insert-format-handler]). 930 931 @itemize[ 932 @item{If @racket[filename] is a string, this function checks the result 933 of @racket[group:get-the-frame-group] to see if the 934 @racket[filename] is already open by a frame in the group. 935 @itemize[ 936 @item{If so, it returns the frame.} 937 @item{If not, this function calls 938 @racket[handler:find-format-handler] with 939 @racket[filename]. 940 @itemize[ 941 @item{If a handler is found, it is applied to 942 @racket[filename] and its result is the final 943 result.} 944 @item{If not, @racket[make-default] is used.}]}]} 945 @item{If @racket[filename] is @racket[#f], @racket[make-default] is 946 used.}]}) 947 948 (parameter-doc 949 handler:current-create-new-window 950 (parameter/c (-> (or/c false/c path?) (is-a?/c frame%))) 951 proc 952 @{This is a parameter that controls how the framework creates new application 953 windows. 954 955 The default setting is this: 956 @racketblock[(λ (filename) 957 (let ([frame (make-object frame:text-info-file% filename)]) 958 (send frame show #t) 959 frame))]}) 960 961 (proc-doc/names 962 handler:open-file 963 (->* () 964 ((or/c false/c path? string?)) 965 (or/c false/c (is-a?/c frame:basic<%>))) 966 (() 967 ((dir #f))) 968 @{This function queries the user for a filename and opens the file for 969 editing. It uses @racket[handler:edit-file] to open the file, once the 970 user has chosen it. 971 972 Calls @racket[finder:get-file] and @racket[handler:edit-file], passing 973 along @racket[dir].}) 974 975 (proc-doc/names 976 handler:install-recent-items 977 ((is-a?/c menu%) . -> . void?) 978 (menu) 979 @{This function deletes all of the items in the given menu and adds one menu 980 item for each recently opened file. These menu items, when selected, call 981 @racket[handler:edit-file] with the filename of the recently opened file. 982 983 The menu's size is limited to 10.}) 984 985 (proc-doc/names 986 handler:set-recent-items-frame-superclass 987 ((implementation?/c frame:standard-menus<%>) . -> . void?) 988 (frame) 989 @{Sets the superclass for the recently opened files frame. It must be 990 derived from @racket[frame:standard-menus].}) 991 992 (proc-doc/names 993 handler:add-to-recent 994 (path? . -> . void?) 995 (filename) 996 @{Adds a filename to the list of recently opened files.}) 997 998 (proc-doc/names 999 handler:set-recent-position 1000 (path? number? number? . -> . void?) 1001 (filename start end) 1002 @{Sets the selection of the recently opened file to @racket[start] and 1003 @racket[end].}) 1004 1005 (proc-doc/names 1006 handler:size-recently-opened-files 1007 (number? . -> . void?) 1008 (num) 1009 @{Sizes the @racket['framework:recently-opened-files/pos] preference list 1010 length to @racket[num].}) 1011 1012 (proc-doc/names 1013 icon:get-paren-highlight-bitmap 1014 (-> (is-a?/c bitmap%)) 1015 () 1016 @{This returns the parenthesis highlight @racket[bitmap%]. It is only used 1017 on black and white screens.}) 1018 1019 (proc-doc/names 1020 icon:get-eof-bitmap 1021 (-> (is-a?/c bitmap%)) 1022 () 1023 @{This returns the @racket[bitmap%] used for the clickable ``eof'' icon from 1024 @racket[text:ports].}) 1025 1026 (proc-doc/names 1027 icon:get-autowrap-bitmap 1028 (-> (is-a?/c bitmap%)) 1029 () 1030 @{This returns the autowrap's @racket[bitmap%]. 1031 1032 The bitmap may not respond @racket[#t] to the @method[bitmap% ok?] 1033 method.}) 1034 1035 (proc-doc/names 1036 icon:get-lock-bitmap 1037 (-> (is-a?/c bitmap%)) 1038 () 1039 @{This returns the lock's @racket[bitmap]. 1040 1041 The bitmap may not respond @racket[#t] to the @method[bitmap% ok?] 1042 method.}) 1043 1044 (proc-doc/names 1045 icon:get-unlock-bitmap 1046 (-> (is-a?/c bitmap%)) 1047 () 1048 @{This returns the reset unlocked @racket[bitmap]. 1049 1050 The bitmap may not respond @racket[#t] to the @method[bitmap% ok?] 1051 method.}) 1052 1053 (proc-doc/names 1054 icon:get-anchor-bitmap 1055 (-> (is-a?/c bitmap%)) 1056 () 1057 @{This returns the anchor's @racket[bitmap]. 1058 1059 The bitmap may not respond @racket[#t] to the @method[bitmap% ok?] 1060 method.}) 1061 1062 (proc-doc/names 1063 icon:get-left/right-cursor 1064 (-> (is-a?/c cursor%)) 1065 () 1066 @{This function returns a @racket[cursor%] object that indicates left/right 1067 sizing is possible, for use with columns inside a window. 1068 1069 The cursor may not respond @racket[#t] to the @method[cursor% ok?] 1070 method.}) 1071 1072 (proc-doc/names 1073 icon:get-up/down-cursor 1074 (-> (is-a?/c cursor%)) 1075 () 1076 @{This function returns a @racket[cursor%] object that indicates up/down 1077 sizing is possible, for use with columns inside a window. 1078 1079 The cursor may not respond @racket[#t] to the @method[cursor% ok?] 1080 method.}) 1081 1082 (proc-doc/names 1083 icon:get-gc-on-bitmap 1084 (-> (is-a?/c bitmap%)) 1085 () 1086 @{This returns a bitmap to be displayed in an @racket[frame:info<%>] frame 1087 when garbage collection is taking place. 1088 1089 The bitmap may not respond @racket[#t] to the @method[bitmap% ok?] 1090 method.}) 1091 1092 (proc-doc/names 1093 icon:get-gc-off-bitmap 1094 (-> (is-a?/c bitmap%)) 1095 () 1096 @{This returns a bitmap to be displayed in an @racket[frame:info<%>] frame 1097 when garbage collection is not taking place. 1098 1099 The bitmap may not respond @racket[#t] to the @method[bitmap% ok?] 1100 method.}) 1101 1102 (proc-doc/names 1103 keymap:remove-user-keybindings-file 1104 (-> any/c any) 1105 (user-keybindings-path) 1106 @{Removes the keymap previously added by 1107 @racket[keymap:add-user-keybindings-file].}) 1108 1109 (proc-doc/names 1110 keymap:add-user-keybindings-file 1111 (-> any/c any) 1112 (user-keybindings-path-or-require-spec) 1113 @{Chains the keymap defined by @racket[user-keybindings-path-or-require-spec] 1114 to the global keymap, returned by @racket[keymap:get-global]. 1115 1116 If @racket[user-keybindings-path-or-require-spec] is a path, the module is 1117 loaded directly from that path. Otherwise, 1118 @racket[user-keybindings-path-or-require-spec] is treated like an argument 1119 to @racket[require].}) 1120 1121 (parameter-doc 1122 keymap:add-to-right-button-menu 1123 (parameter/c 1124 (-> (is-a?/c popup-menu%) 1125 (is-a?/c editor<%>) 1126 (is-a?/c event%) 1127 void?)) 1128 proc 1129 @{When the keymap that @racket[keymap:get-global] returns is installed into 1130 an editor, this parameter's value is used for right button clicks. 1131 1132 Before calling this procedure, the function 1133 @racket[append-editor-operation-menu-items] is called. 1134 1135 See also @racket[keymap:add-to-right-button-menu/before].}) 1136 1137 (parameter-doc 1138 keymap:add-to-right-button-menu/before 1139 (parameter/c 1140 (-> (is-a?/c popup-menu%) (is-a?/c editor<%>) (is-a?/c event%) void?)) 1141 proc 1142 @{When the keymap that @racket[keymap:get-global] returns is installed into 1143 an editor, this function is called for right button clicks. 1144 1145 After calling this procedure, the function 1146 @racket[append-editor-operation-menu-items] is called. 1147 1148 See also @racket[keymap:add-to-right-button-menu].}) 1149 1150 (proc-doc/names 1151 keymap:call/text-keymap-initializer 1152 ((-> any/c) . -> . any/c) 1153 (thunk-proc) 1154 @{This function parameterizes the call to @racket[thunk-proc] by setting the 1155 keymap-initialization procedure (see 1156 @racket[current-text-keymap-initializer]) to install the framework's 1157 standard text bindings.}) 1158 1159 (proc-doc/names 1160 keymap:canonicalize-keybinding-string 1161 (string? . -> . string?) 1162 (keybinding-string) 1163 @{Returns a string that denotes the same keybindings as the input string, 1164 except that it is in canonical form; two canonical keybinding strings can 1165 be compared with @racket[string=?].}) 1166 1167 (proc-doc/names 1168 keymap:get-editor 1169 (-> (is-a?/c keymap%)) 1170 () 1171 @{This returns a keymap for handling standard editing operations. It binds 1172 these keys: 1173 1174 @itemize[ 1175 @item{@racket["z"]: undo} 1176 @item{@racket["y"]: redo} 1177 @item{@racket["x"]: cut} 1178 @item{@racket["c"]: copy} 1179 @item{@racket["v"]: paste} 1180 @item{@racket["a"]: select all}] 1181 where each key is prefixed with the menu-shortcut key, based on the 1182 platform. Under Unix, the shortcut is @racket["a:"]; under windows the 1183 shortcut key is @racket["c:"] and under MacOS, the shortcut key is 1184 @racket["d:"].}) 1185 1186 (proc-doc/names 1187 keymap:get-file 1188 (-> (is-a?/c keymap%)) 1189 () 1190 @{This returns a keymap for handling file operations.}) 1191 1192 (proc-doc/names 1193 keymap:get-user 1194 (-> (is-a?/c keymap%)) 1195 () 1196 @{This returns a keymap that contains all of the keybindings in the keymaps 1197 loaded via @racket[keymap:add-user-keybindings-file]}) 1198 1199 (proc-doc/names 1200 keymap:get-global 1201 (-> (is-a?/c keymap%)) 1202 () 1203 @{This returns a keymap for general operations. See 1204 @racket[keymap:setup-global] for a list of the bindings this keymap 1205 contains.}) 1206 1207 (proc-doc/names 1208 keymap:get-search 1209 (-> (is-a?/c keymap%)) 1210 () 1211 @{This returns a keymap for searching operations.}) 1212 1213 (proc-doc/names 1214 keymap:make-meta-prefix-list 1215 (->* (string?) (boolean?) (listof string?)) 1216 ((key) 1217 ((mask-control? #f))) 1218 @{This prefixes a key with all of the different meta prefixes and returns a 1219 list of the prefixed strings. If @racket[mask-control?] is @racket[#t], 1220 then the result strings include @racket["~c:"] in them 1221 (see @racket[keymap:send-map-function-meta]) for a fuller discussion of this 1222 boolean). 1223 1224 Takes a keymap, a base key specification, and a function name; it prefixes 1225 the base key with all ``meta'' combination prefixes, and installs the new 1226 combinations into the keymap. For example, 1227 @racket[(keymap:send-map-function-meta keymap "a" func)] maps 1228 @racket["m:a"] and @racket["ESC;a"] to @racket[func].}) 1229 1230 (proc-doc/names 1231 keymap:send-map-function-meta 1232 (->* ((is-a?/c keymap%) string? string?) 1233 (boolean? #:alt-as-meta-keymap (or/c (is-a?/c keymap%) #f)) 1234 void?) 1235 ((keymap key func) 1236 ((mask-control? #f) 1237 (alt-as-meta-keymap #f))) 1238 @{@index{Meta} Most keyboard and mouse mappings are inserted into a keymap by 1239 calling the keymap's @method[keymap% map-function] method. However, 1240 ``meta'' combinations require special attention. The @racket["m:"] prefix 1241 recognized by @method[keymap% map-function] applies only to the Meta key 1242 that exists on some keyboards. By convention, however, ``meta'' 1243 combinations can also be accessed by using ``ESC'' as a prefix. 1244 1245 This procedure binds all of the key-bindings obtained by prefixing 1246 @racket[key] with a meta-prefix to @racket[func] in @racket[keymap]. 1247 1248 If @racket[alt-as-meta-keymap] is a @racket[keymap%] object, then the 1249 the key binding @racket[(string-append "?:a:" key)] is bound to 1250 @racket[func] in @racket[alt-as-meta-keymap]. Additionally, if 1251 @racket[func] has not been added (via @method[add-function keymap%]) 1252 to @racket[alt-as-meta-keymap], then @racket[keymap:send-map-function-meta] 1253 signals an error. 1254 1255 If @racket[mask-control?] is @racket[#t], 1256 then the result strings include @racket["~c:"] in them. 1257 This is important under Windows where international keyboards 1258 often require characters that are unmodified on US keyboards to 1259 be typed with the AltGr key; such keys come into the system as 1260 having both the control and the meta modified applied to them and, 1261 generally speaking, keybindings should not change the behavior of 1262 those keys.}) 1263 1264 (proc-doc/names 1265 keymap:setup-editor 1266 ((is-a?/c keymap%) . -> . void?) 1267 (keymap) 1268 @{This sets up the input keymap with the bindings described in 1269 @racket[keymap:get-editor].}) 1270 1271 (proc-doc/names 1272 keymap:setup-file 1273 ((is-a?/c keymap%) . -> . void?) 1274 (keymap) 1275 @{This extends a @racket[keymap%] with the bindings for files.}) 1276 1277 (proc-doc/names 1278 keymap:setup-global 1279 (((is-a?/c keymap%)) 1280 (#:alt-as-meta-keymap (or/c #f (is-a?/c keymap%))) 1281 . ->* . void?) 1282 ((keymap) ([alt-as-meta-keymap #f])) 1283 @{This function extends a @racket[keymap%] with the following functions: 1284 @itemize[ 1285 @item{@mapdesc[ring-bell any] --- Rings the bell (using @racket[bell]) 1286 and removes the search panel from the frame, if there.} 1287 @item{@mapdesc[save-file key] --- Saves the buffer. If the buffer has no 1288 name, then @racket[finder:put-file]@index["finder:put-file"] is 1289 invoked.} 1290 @item{@mapdesc[save-file-as key] --- Calls 1291 @racket[finder:put-file]@index["finder:put-file"] to save the 1292 buffer.} 1293 @item{@mapdesc[load-file key] --- Invokes 1294 @racket[finder:open-file]@index["finder:open-file"].} 1295 @item{@mapdesc[find-string key] --- Opens the search buffer at the bottom 1296 of the frame, unless it is already open, in which case it searches 1297 for the text in the search buffer.} 1298 @item{@mapdesc[find-string-reverse key] --- Same as ``find-string'', but 1299 in the reverse direction.} 1300 @item{@mapdesc[find-string-replace key] --- Opens a replace string dialog 1301 box.} 1302 @item{@mapdesc[toggle-anchor key] --- Turns selection-anchoring on or 1303 off.} 1304 @item{@mapdesc[center-view-on-line key] --- Centers the buffer in its 1305 display using the currently selected line.} 1306 @item{@mapdesc[collapse-space key] --- Collapses all non-return 1307 whitespace around the caret into a single space.} 1308 @item{@mapdesc[remove-space key] --- Removes all non-return whitespace 1309 around the caret.} 1310 @item{@mapdesc[collapse-newline key] --- Collapses all empty lines around 1311 the caret into a single empty line. If there is only one empty 1312 line, it is removed.} 1313 @item{@mapdesc[open-line key] --- Inserts a new line.} 1314 @item{@mapdesc[transpose-chars key] --- Transposes the characters before 1315 and after the caret and moves forward one position.} 1316 @item{@mapdesc[transpose-words key] --- Transposes words before and after 1317 the caret and moves forward one word.} 1318 @item{@mapdesc[capitalize-word key] --- Changes the first character of 1319 the next word to a capital letter and moves to the end of the 1320 word.} 1321 @item{@mapdesc[upcase-word key] --- Changes all characters of the next 1322 word to capital letters and moves to the end of the word.} 1323 @item{@mapdesc[downcase-word key] --- Changes all characters of the next 1324 word to lowercase letters and moves to the end of the word.} 1325 @item{@mapdesc[kill-word key] --- Kills the next word.} 1326 @item{@mapdesc[backward-kill-word key] --- Kills the previous word.} 1327 @item{@mapdesc[goto-line any] --- Queries the user for a line number and 1328 moves the caret there.} 1329 @item{@mapdesc[goto-position any] --- Queries the user for a position 1330 number and moves the caret there.} 1331 @item{@mapdesc[copy-clipboard mouse] --- Copies the current selection to 1332 the clipboard.} 1333 @item{@mapdesc[cut-clipboard mouse] --- Cuts the current selection to the 1334 clipboard.} 1335 @item{@mapdesc[paste-clipboard mouse] --- Pastes the clipboard to the 1336 current selection.} 1337 @item{@mapdesc[copy-click-region mouse] --- Copies the region between the 1338 caret and the input mouse event.} 1339 @item{@mapdesc[cut-click-region mouse] --- Cuts the region between the 1340 caret and the input mouse event.} 1341 @item{@mapdesc[paste-click-region mouse] --- Pastes the clipboard into 1342 the position of the input mouse event.} 1343 @item{@mapdesc[select-click-word mouse] --- Selects the word under the 1344 input mouse event.} 1345 @item{@mapdesc[select-click-line mouse] --- Selects the line under the 1346 input mouse event.} 1347 @item{@mapdesc[start-macro key] -- Starts recording a keyboard macro} 1348 @item{@mapdesc[end-macro key] --- Stops recording a keyboard macro} 1349 @item{@mapdesc[do-macro key] --- Executes the last keyboard macro} 1350 @item{@mapdesc[toggle-overwrite key] --- Toggles overwriting mode}] 1351 1352 These functions are bound to the following keys 1353 (C = control, S = shift, A = alt, M = ``meta'', D = command): 1354 1355 @itemize[ 1356 @item{C-g : ``ring-bell''} 1357 @item{M-C-g : ``ring-bell''} 1358 @item{C-c C-g : ``ring-bell''} 1359 @item{C-x C-g : ``ring-bell''} 1360 @item{C-p : ``previous-line''} 1361 @item{S-C-p : ``select-previous-line''} 1362 @item{C-n : ``next-line''} 1363 @item{S-C-n : ``select-next-line''} 1364 @item{C-e : ``end-of-line''} 1365 @item{S-C-e : ``select-to-end-of-line''} 1366 @item{D-RIGHT : ``end-of-line''} 1367 @item{S-D-RIGHT : ``select-to-end-of-line''} 1368 @item{M-RIGHT : ``end-of-line''} 1369 @item{S-M-RIGHT : ``select-to-end-of-line''} 1370 @item{C-a : ``beginning-of-line''} 1371 @item{S-C-a : ``select-to-beginning-of-line''} 1372 @item{D-LEFT : ``beginning-of-line''} 1373 @item{D-S-LEFT : ``select-to-beginning-of-line''} 1374 @item{M-LEFT : ``beginning-of-line''} 1375 @item{M-S-LEFT : ``select-to-beginning-of-line''} 1376 @item{C-h : ``delete-previous-character''} 1377 @item{C-d : ``delete-next-character''} 1378 @item{C-f : ``forward-character''} 1379 @item{S-C-f : ``select-forward-character''} 1380 @item{C-b : ``backward-character''} 1381 @item{S-C-b : ``select-backward-character''} 1382 @item{M-f : ``forward-word''} 1383 @item{S-M-f : ``select-forward-word''} 1384 @item{A-RIGHT : ``forward-word''} 1385 @item{A-S-RIGHT : ``forward-select-word''} 1386 @item{M-b : ``backward-word''} 1387 @item{S-M-b : ``select-backward-word''} 1388 @item{A-LEFT : ``backward-word''} 1389 @item{A-S-LEFT : ``backward-select-word''} 1390 @item{M-d : ``kill-word''} 1391 @item{M-DELETE : ``backward-kill-word''} 1392 @item{M-c : ``capitalize-word''} 1393 @item{M-u : ``upcase-word''} 1394 @item{M-l : ``downcase-word''} 1395 @item{M-< : ``beginning-of-file''} 1396 @item{S-M-< : ``select-to-beginning-of-file''} 1397 @item{M-> : ``end-of-file''} 1398 @item{S-M-> : ``select-to-end-of-file''} 1399 @item{C-v : ``next-page''} 1400 @item{S-C-v : ``select-next-page''} 1401 @item{M-v : ``previous-page''} 1402 @item{S-M-v : ``select-previous-page''} 1403 @item{C-l : ``center-view-on-line''} 1404 @item{C-k : ``delete-to-end-of-line''} 1405 @item{C-y : ``paste-clipboard'' (Except Windows)} 1406 @item{A-v : ``paste-clipboard''} 1407 @item{D-v : ``paste-clipboard''} 1408 @item{C-_ : ``undo''} 1409 @item{C-x u : ``undo''} 1410 @item{C-+ : ``redo''} 1411 @item{C-w : ``cut-clipboard''} 1412 @item{M-w : ``copy-clipboard''} 1413 @item{C-x C-s : ``save-file''} 1414 @item{C-x C-w : ``save-file-as''} 1415 @item{C-x C-f : ``load-file''} 1416 @item{C-s : ``find-string''} 1417 @item{C-r : ``find-string-reverse''} 1418 @item{M-% : ``find-string-replace''} 1419 @item{SPACE : ``collapse-space''} 1420 @item{M-Backslash : ``remove-space''} 1421 @item{C-x C-o : ``collapse-newline''} 1422 @item{C-o : ``open-line''} 1423 @item{C-t : ``transpose-chars''} 1424 @item{M-t : ``transpose-words''} 1425 @item{C-SPACE : ``toggle-anchor''} 1426 @item{M-g : ``goto-line''} 1427 @item{M-p : ``goto-position''} 1428 @item{LEFTBUTTONTRIPLE : ``select-click-line''} 1429 @item{LEFTBUTTONDOUBLE : ``select-click-word''} 1430 @item{RIGHTBUTTON : ``copy-click-region''} 1431 @item{RIGHTBUTTONDOUBLE : ``cut-click-region''} 1432 @item{MIDDLEBUTTON : ``paste-click-region''} 1433 @item{C-RIGHTBUTTON : ``copy-clipboard''} 1434 @item{INSERT : ``toggle-overwrite''} 1435 @item{M-o : ``toggle-overwrite''}] 1436 1437 If @racket[alt-as-meta-keymap] is not @racket[#f], then for each 1438 of the M- mappings, a ``flexible'' A- variant of the mapping is added to 1439 @racket[alt-as-meta-keymap]. The flexible mapping matches a key combination 1440 where the non-modifier part of the mapping would match if the modifier 1441 had not affected the non-modifier part (e.g., matching Option-p as A-p on Mac OS 1442 even when an Option-p combination produces ``π''). 1443 1444 @history[#:changed "1.34" @elem{Added the @racket[#:alt-as-meta-keymap] argument.}]}) 1445 1446 (proc-doc/names 1447 keymap:setup-search 1448 ((is-a?/c keymap%) . -> . void?) 1449 (keymap) 1450 @{This extends a @racket[keymap%] with the bindings for searching.}) 1451 1452 (proc-doc/names 1453 keymap:set-chained-keymaps 1454 ((is-a?/c keymap:aug-keymap<%>) 1455 (listof (is-a?/c keymap%)) 1456 . -> . 1457 void?) 1458 (keymap children-keymaps) 1459 @{Sets @racket[keymap]'s chained keymaps to @racket[children-keymaps], 1460 unchaining any keymaps that are currently chained to @racket[keymap].}) 1461 1462 (proc-doc/names 1463 keymap:remove-chained-keymap 1464 ((is-a?/c editor<%>) 1465 (is-a?/c keymap:aug-keymap<%>) 1466 . -> . 1467 void?) 1468 (editor keymap) 1469 @{Removes @racket[keymap] from the keymaps chained to @racket[editor]. 1470 Also (indirectly) removes all keymaps chained to @racket[keymap] from 1471 @racket[editor], since they are removed when unchaining @racket[keymap] 1472 itself. 1473 1474 Each of the keymaps chained to @racket[editor] must be an 1475 @racket[keymap:aug-keymap%] and @racket[keymap] cannot be the result of 1476 @racket[(send editor get-keymap)] That is, @racket[keymap] must be chained 1477 to some keymap attached to the editor.}) 1478 1479 (proc-doc/names 1480 keymap:region-click 1481 (-> any/c any/c (-> number? boolean? number? number? any) 1482 any) 1483 (text mouse-event f) 1484 @{Calls @racket[f] after computing where the @racket[event] 1485 corresponds to in the @racket[text]. If @racket[event] is 1486 not a @racket[mouse-event%] object or if @racket[text] is not a 1487 @racket[text%] object, this function does nothing, returning 1488 @racket[(void)]. 1489 1490 The arguments to @racket[f] are: 1491 @itemize[@item{the position where the click occurred} 1492 @item{a boolean indicating if the position is at 1493 the right-hand edge of the screen (to 1494 cover the eol ambiguity)}]}) 1495 1496 (proc-doc/names 1497 racket:text-balanced? 1498 (->* ((is-a?/c text%)) 1499 (number? (or/c false/c number?)) 1500 boolean?) 1501 ((text) 1502 ((start 0) (end #f))) 1503 @{Determines if the range in the editor from @racket[start] to @racket[end] 1504 in @racket[text] has at least one complete s-expression and there are no 1505 incomplete s-expressions. If @racket[end] is @racket[#f], it defaults to 1506 the last position of the @racket[text]. The designation ``complete'' is 1507 defined to be something that does not cause @racket[read] to raise a 1508 @racket[exn:fail:read:eof?] exception, so there may be all kinds of strange 1509 read-level (not to speak of parse level) errors in the expressions. 1510 1511 The implementation of this function creates a port with 1512 @racket[open-input-text-editor] and then uses @racket[read] to parse the 1513 range of the buffer.}) 1514 1515 (proc-doc/names 1516 racket:add-preferences-panel 1517 (-> void?) 1518 () 1519 @{Adds a tabbing preferences panel to the preferences dialog.}) 1520 1521 (proc-doc/names 1522 racket:get-keymap 1523 (-> (is-a?/c keymap%)) 1524 () 1525 @{Returns a keymap with binding suitable for Racket.}) 1526 1527 (proc-doc/names 1528 racket:add-coloring-preferences-panel 1529 (-> any) 1530 () 1531 @{Installs the ``Racket'' preferences panel in the ``Syntax Coloring'' 1532 section.}) 1533 1534 (proc-doc/names 1535 racket:get-color-prefs-table 1536 (-> (listof (list/c symbol? (is-a?/c color%) string?))) 1537 () 1538 @{Returns a table mapping from symbols (naming the categories that the online 1539 colorer uses for Racket mode coloring) to their colors. 1540 1541 These symbols are suitable for input to 1542 @racket[racket:short-sym->pref-name] and 1543 @racket[racket:short-sym->style-name]. 1544 1545 See also @racket[racket:get-white-on-black-color-prefs-table].}) 1546 1547 (proc-doc/names 1548 racket:get-white-on-black-color-prefs-table 1549 (-> (listof (list/c symbol? (is-a?/c color%) string?))) 1550 () 1551 @{Returns a table mapping from symbols (naming the categories that the online 1552 colorer uses for Racket mode coloring) to their colors when the user 1553 chooses the white-on-black mode in the preferences dialog. 1554 1555 See also @racket[racket:get-color-prefs-table].}) 1556 1557 (proc-doc/names 1558 racket:short-sym->pref-name 1559 (symbol? . -> . symbol?) 1560 (short-sym) 1561 @{Builds the symbol naming the preference from one of the symbols in the 1562 table returned by @racket[racket:get-color-prefs-table].}) 1563 1564 (proc-doc/names 1565 racket:short-sym->style-name 1566 (symbol? . -> . string?) 1567 (short-sym) 1568 @{Builds the symbol naming the editor style from one of the symbols in the 1569 table returned by @racket[racket:get-color-prefs-table]. This style is a 1570 named style in the style list returned by 1571 @racket[editor:get-standard-style-list].}) 1572 1573 (proc-doc/names 1574 racket:get-wordbreak-map 1575 (-> (is-a?/c editor-wordbreak-map%)) 1576 () 1577 @{This method returns a @racket[editor-wordbreak-map%] that is suitable for 1578 Racket.}) 1579 1580 (proc-doc/names 1581 racket:init-wordbreak-map 1582 ((is-a?/c keymap%) . -> . void?) 1583 (key) 1584 @{Initializes the workdbreak map for @racket[keymap].}) 1585 1586 (proc-doc/names 1587 racket:setup-keymap 1588 (((is-a?/c keymap%)) 1589 (#:alt-as-meta-keymap (or/c #f (is-a?/c keymap%))) 1590 . ->* . void?) 1591 ((keymap) ([alt-as-meta-keymap #f])) 1592 @{Initializes @racket[keymap] with Racket-mode keybindings. The 1593 @racket[alt-as-meta-keymap] argument is treated the same as 1594 for @racket[keymap:setup-global]. 1595 1596 @history[#:changed "1.40" @elem{Added the @racket[#:alt-as-meta-keymap] argument.}]}) 1597 1598 (parameter-doc 1599 editor:doing-autosave? 1600 (parameter/c boolean?) 1601 autosaving? 1602 @{A parameter that indicates whether or not we are currently saving 1603 the editor because of an autosave. See also 1604 @method[editor:backup-autosave<%> do-autosave].}) 1605 (proc-doc/names 1606 editor:set-current-preferred-font-size 1607 (-> exact-nonnegative-integer? void?) 1608 (new-size) 1609 @{Sets the font preference for the current monitor configuration to 1610 @racket[new-size]. 1611 1612 See also @racket[editor:get-current-preferred-font-size] 1613 and @racket[editor:font-size-pref->current-font-size].}) 1614 1615 (proc-doc 1616 editor:get-current-preferred-font-size 1617 (-> exact-nonnegative-integer?) 1618 @{Gets the current setting for the font size preference. Calls 1619 @racket[editor:font-size-pref->current-font-size] with the 1620 current preference setting. 1621 1622 See also @racket[editor:set-current-preferred-font-size] and 1623 @racket[editor:get-change-font-size-when-monitors-change?]. 1624 }) 1625 1626 (proc-doc/names 1627 editor:font-size-pref->current-font-size 1628 (-> (vector/c 1629 ;; font sizes for specific monitor configurations 1630 (hash/c 1631 ;; a particular monitor configuration: the widths and heights 1632 (non-empty-listof (list/c exact-nonnegative-integer? 1633 exact-nonnegative-integer?)) 1634 ;; the font size for that configuration 1635 exact-nonnegative-integer? 1636 #:flat? #t) 1637 1638 ;; default font size, when none of the configs above apply 1639 exact-nonnegative-integer? 1640 #:flat? #t) 1641 exact-nonnegative-integer?) 1642 (font-preference) 1643 @{Determines the current monitor configuration and uses that to pick 1644 one of the sizes from its argument. The argument is expected 1645 to come from the preference value of @racket['framework:standard-style-list:font-size]. 1646 1647 Except if @racket[editor:get-change-font-size-when-monitors-change?] returns 1648 @racket[#f], in which case the current monitor configuration is not considered 1649 and the last-set size (the second position in the vector) is always returned. 1650 1651 As background, the font size 1652 preference is actually saved on a per-monitor configuration basis; specifically 1653 the preference value (using the same contract as the argument of this function) 1654 contains a table mapping a list of monitor sizes (but not their 1655 positions) obtained by @racket[get-display-size] to the preferred font size 1656 (plus a default size used for new configurations). 1657 1658 See also @racket[editor:get-current-preferred-font-size], 1659 @racket[editor:get-current-preferred-font-size], and 1660 @racket[editor:get-change-font-size-when-monitors-change?].}) 1661 1662 (proc-doc/names 1663 editor:get-change-font-size-when-monitors-change? 1664 (-> boolean?) 1665 () 1666 @{Returns @racket[#t] when the framework will automatically 1667 adjust the current font size in the @racket["Standard"] 1668 style of the result of @racket[editor:get-standard-style-list] 1669 based on the monitor configuration. 1670 1671 Defaults to @racket[#f] 1672 1673 See also @racket[editor:set-change-font-size-when-monitors-change?]; 1674 @racket[editor:font-size-pref->current-font-size].}) 1675 1676 (proc-doc/names 1677 editor:set-change-font-size-when-monitors-change? 1678 (-> boolean? void?) 1679 (b?) 1680 @{Controls the result of @racket[editor:get-change-font-size-when-monitors-change?]. 1681 1682 See also @racket[editor:get-change-font-size-when-monitors-change?].}) 1683 1684 (proc-doc/names 1685 editor:set-default-font-color 1686 (->* ((is-a?/c color%)) ((or/c #f (is-a?/c color%))) void?) 1687 ((fg-color) ((bg-color #f))) 1688 @{Sets the foreground color of the style named 1689 @racket[editor:get-default-color-style-name] to @racket[fg-color]. 1690 If @racket[bg-color] is not @racket[#f], then @racket[editor:set-default-font-color] 1691 sets the background color to @racket[bg-color].}) 1692 1693 (proc-doc/names 1694 editor:get-default-color-style-name 1695 (-> string?) 1696 () 1697 @{The name of the style (in the list returned by 1698 @racket[editor:get-standard-style-list]) that holds the default color.}) 1699 1700 (proc-doc/names 1701 editor:set-standard-style-list-delta 1702 (-> string? (is-a?/c style-delta%) void?) 1703 (name delta) 1704 @{Finds (or creates) the style named by @racket[name] in the result of 1705 @racket[editor:get-standard-style-list] and sets its delta to 1706 @racket[delta]. 1707 1708 If the style named by @racket[name] is already in the style list, it must 1709 be a delta style.}) 1710 1711 (proc-doc/names 1712 editor:set-standard-style-list-pref-callbacks 1713 (-> any) 1714 () 1715 @{Installs the font preference callbacks that update the style list returned 1716 by @racket[editor:get-standard-style-list] based on the font preference 1717 symbols.}) 1718 1719 (proc-doc/names 1720 editor:get-standard-style-list 1721 (-> (is-a?/c style-list%)) 1722 () 1723 @{Returns a style list that is used for all instances of 1724 @racket[editor:standard-style-list%].}) 1725 1726 (proc-doc/names 1727 editor:add-after-user-keymap 1728 (-> (is-a?/c keymap%) (listof (is-a?/c keymap%)) (listof (is-a?/c keymap%))) 1729 (keymap keymaps) 1730 @{Returns a list that contains all of the keymaps in @racket[keymaps], in the 1731 same relative order, but also with @racket[keymap], where @racket[keymap] 1732 is now the first keymap after @racket[keymap:get-user] (if that keymap is 1733 in the list.)}) 1734 1735 (proc-doc/names 1736 panel:dragable-container-size 1737 (-> (listof (list/c real? real? boolean? boolean?)) real? boolean? 1738 (values real? real?)) 1739 (container-info bar-thickness vertical?) 1740 @{Returns the minimum width and height for a @racket[panel:dragable<%>] object 1741 where @racket[container-info] (see @method[area-container<%> container-size] for 1742 more details on that argument) is the children's info, and @racket[bar-thickness] and 1743 @racket[vertical?] indicate the properties of the panel. 1744 1745 This function is exported mostly for the test suite.}) 1746 1747 (proc-doc/names 1748 panel:dragable-place-children 1749 (-> (listof (list/c real? real? boolean? boolean?)) 1750 real? 1751 real? 1752 (listof (between/c 0 1)) 1753 real? 1754 boolean? 1755 (values (listof (list/c (integer-in 0 10000) 1756 (integer-in 0 10000) 1757 (integer-in 0 10000) 1758 (integer-in 0 10000))) 1759 (listof (list/c (integer-in 0 10000) 1760 (integer-in 0 10000))))) 1761 (container-info width height percentages bar-thickness vertical?) 1762 @{Returns the geometry information for a dragable panel. The inputs 1763 are the @racket[container-info] (see @method[area-container<%> place-children] for more info), 1764 the @racket[width] and @racket[height] of the window, the @racket[percentages] for the spacing 1765 of the children, and a real and a boolean indicating the thickness of the bar between 1766 the child panels and whether or not this is a vertical panel, respectively. 1767 1768 This function is exported mostly for the test suite.}) 1769 1770 (proc-doc/names 1771 color-model:rgb->xyz 1772 (number? number? number? . -> . color-model:xyz?) 1773 (r g b) 1774 @{Converts a color represented as a red-green-blue tuple (each value from 0 1775 to 255) into an XYZ tuple. This describes a point in the CIE 1776 XYZ color space.}) 1777 1778 (proc-doc/names 1779 color-model:rgb-color-distance 1780 (number? number? number? number? number? number? . -> . number?) 1781 (red-a green-a blue-a red-b green-b blue-b) 1782 @{This calculates a distance between two colors. The smaller the distance, 1783 the closer the colors should appear to the human eye. A distance of 10 is 1784 reasonably close that it could be called the same color. 1785 1786 This function is not symmetric in red, green, and blue, so it is important 1787 to pass red, green, and blue components of the colors in the proper order. 1788 The first three arguments are red, green and blue for the first color, 1789 respectively, and the second three arguments are red green and blue for the 1790 second color, respectively.}) 1791 1792 (proc-doc/names 1793 color-model:xyz->rgb 1794 (number? number? number? . -> . (list/c number? number? number?)) 1795 (x y z) 1796 @{Converts an XYZ-tuple (in the CIE XYZ colorspace) into a list of values 1797 representing an RGB-tuple.}) 1798 1799 (proc-doc/names 1800 color-model:xyz? 1801 (any/c . -> . boolean?) 1802 (val) 1803 @{Determines if @racket[val] an xyz color record.}) 1804 1805 (proc-doc/names 1806 color-model:xyz-x 1807 (color-model:xyz? . -> . number?) 1808 (xyz) 1809 @{Extracts the x component of @racket[xyz].}) 1810 1811 (proc-doc/names 1812 color-model:xyz-y 1813 (color-model:xyz? . -> . number?) 1814 (xyz) 1815 @{Extracts the y component of @racket[xyz].}) 1816 1817 (proc-doc/names 1818 color-model:xyz-z 1819 (color-model:xyz? . -> . number?) 1820 (xyz) 1821 @{Extracts the z component of @racket[xyz].}) 1822 1823 (proc-doc/names 1824 color-model:hsl->rgb 1825 (-> (real-in 0 360) (real-in 0 1) (real-in 0 1) 1826 (values byte? byte? byte?)) 1827 (hue saturation lightness) 1828 @{Computes rgb color values for the hsl color inputs.}) 1829 1830 (proc-doc/names 1831 color-model:rgb->hsl 1832 (-> byte? byte? byte? 1833 (values (real-in 0 360) (real-in 0 1) (real-in 0 1))) 1834 (red green blue) 1835 @{Computes hsl color values for the rgb color inputs.}) 1836 1837 (proc-doc/names 1838 color-prefs:set-default/color-scheme 1839 (-> symbol? 1840 (or/c (is-a?/c color%) string?) 1841 (or/c (is-a?/c color%) string?) 1842 void?) 1843 (pref-sym black-on-white-color white-on-black-color) 1844 @{Registers a preference whose value will be updated when the user clicks on 1845 one of the color scheme default settings in the preferences dialog. 1846 1847 Also calls @racket[preferences:set-default] and 1848 @racket[preferences:set-un/marshall] with appropriate arguments to register 1849 the preference.}) 1850 1851 (proc-doc/names 1852 color-prefs:register-color-preference 1853 (->* (symbol? string? (or/c (is-a?/c color%) (is-a?/c style-delta%))) 1854 ((or/c string? (is-a?/c color%) #f) 1855 #:background (or/c (is-a?/c color%) #f)) 1856 void?) 1857 ((pref-name style-name color/sd) 1858 ((white-on-black-color #f) 1859 (background #f))) 1860 @{This function registers a color preference and initializes the style list 1861 returned from @racket[editor:get-standard-style-list]. In particular, it 1862 calls @racket[preferences:set-default] and 1863 @racket[preferences:set-un/marshall] to install the pref for 1864 @racket[pref-name], using @racket[color/sd] as the default color. The 1865 preference is bound to a @racket[style-delta%], and initially the 1866 @racket[style-delta%] changes the foreground color to @racket[color/sd], 1867 unless @racket[color/sd] is a style delta already, in which case it is just 1868 used directly. Then, it calls 1869 @racket[editor:set-standard-style-list-delta] passing the 1870 @racket[style-name] and the current value of the preference 1871 @racket[pref-name]. 1872 1873 Finally, it adds calls @racket[preferences:add-callback] to set a callback 1874 for @racket[pref-name] that updates the style list when the preference 1875 changes. 1876 1877 If @racket[white-on-black-color] is not @racket[#f], then the color of the 1878 @racket[color/sd] argument is used in combination with 1879 @racket[white-on-black-color] to register this preference with 1880 @racket[color-prefs:set-default/color-scheme]. 1881 1882 If @racket[background] is not @racket[#f], then it is used to construct the 1883 default background color for the style delta. 1884 }) 1885 1886 (proc-doc/names 1887 color-prefs:add-background-preferences-panel 1888 (-> void?) 1889 () 1890 @{Adds a preferences panel that configures the background color for 1891 @racket[editor:basic-mixin].}) 1892 1893 (proc-doc/names 1894 color-prefs:add-to-preferences-panel 1895 (string? ((is-a?/c vertical-panel%) . -> . void?) . -> . void?) 1896 (name func) 1897 @{Calls @racket[func] with the subpanel of the preferences coloring panel 1898 that corresponds to @racket[name].}) 1899 1900 (proc-doc/names 1901 color-prefs:build-color-selection-panel 1902 (->* ((is-a?/c area-container<%>) symbol? string? string?) 1903 (#:background? boolean?) 1904 void?) 1905 ((parent pref-sym style-name example-text) 1906 ((background? #f))) 1907 @{Builds a panel with a number of controls for configuring a font: its color 1908 (including a background configuration if @racket[background] is @racket[#t]) 1909 and check boxes for bold, italic, and underline. The @racket[parent] 1910 argument specifies where the panel will be placed. The @racket[pref-sym] 1911 should be a preference (suitable for use with @racket[preferences:get] and 1912 @racket[preferences:set]). The @racket[style-name] specifies the name of a 1913 style in the style list returned from 1914 @racket[editor:get-standard-style-list] and @racket[example-text] is shown 1915 in the panel so users can see the results of their configuration.}) 1916 1917 (proc-doc/names 1918 color-prefs:marshall-style-delta 1919 (-> (is-a?/c style-delta%) printable/c) 1920 (style-delta) 1921 @{Builds a printed representation for a style-delta.}) 1922 1923 (proc-doc/names 1924 color-prefs:unmarshall-style-delta 1925 (-> printable/c (or/c false/c (is-a?/c style-delta%))) 1926 (marshalled-style-delta) 1927 @{Builds a style delta from its printed representation. Returns @racket[#f] 1928 if the printed form cannot be parsed.}) 1929 1930 (proc-doc/names 1931 color-prefs:white-on-black 1932 (-> any) 1933 () 1934 @{Sets the colors registered by @racket[color-prefs:register-color-preference] 1935 to their white-on-black variety.}) 1936 1937 (proc-doc/names 1938 color-prefs:black-on-white 1939 (-> any) 1940 () 1941 @{Sets the colors registered by @racket[color-prefs:register-color-preference] 1942 to their black-on-white variety.}) 1943 1944 (proc-doc 1945 color-prefs:add-color-scheme-entry 1946 (->i ([name symbol?] 1947 [black-on-white-color (or/c string? (is-a?/c color%))] 1948 [white-on-black-color (or/c string? (is-a?/c color%))]) 1949 (#:style 1950 [style (or/c #f string?)] 1951 #:bold? [bold (style) (if style (or/c boolean? 'base) #f)] 1952 #:underline? [underline? (style) (if style boolean? #f)] 1953 #:italic? [italic? (style) (if style boolean? #f)] 1954 #:background 1955 [background (style) 1956 (if style 1957 (or/c #f string? (is-a?/c color%)) 1958 #f)]) 1959 [result void?]) 1960 (#f #f #f #f #f) 1961 @{Registers a new color or style named @racket[name] for use in the color schemes. 1962 If @racket[style] is provided, a new style is registered; if not a color is 1963 registered. 1964 1965 The default values of all of the keyword arguments are @racket[#f], except 1966 @racket[bold], which defaults to @racket['base] (if @racket[style] is not @racket[#f]).}) 1967 1968 (proc-doc/names 1969 color-prefs:add-color-scheme-preferences-panel 1970 (->* () (#:extras (-> (is-a?/c panel%) any)) void?) 1971 (() ((extras void))) 1972 @{Adds a panel for choosing a color-scheme to the preferences dialog. 1973 1974 The @racket[extras] argument is called after the color schemes have been added 1975 to the preferences panel. It is passed the panel containing the color schemes 1976 and can add items to it.}) 1977 1978 (proc-doc 1979 color-prefs:register-info-based-color-schemes 1980 (-> void?) 1981 @{Reads 1982 the @filepath{info.rkt} file in each collection, looking for the key 1983 @index{framework:color-schemes} 1984 @racket['framework:color-schemes]. Each definition must bind 1985 a list of hash tables, each of which introduces a new 1986 color scheme. Each hash table should have keys that specify 1987 details of the color scheme, as follows: 1988 @itemlist[@item{@racket['name]: must be either a string or a symbol; 1989 if it is a symbol and @racket[string-constant?], 1990 it is passed to @racket[dynamic-string-constant] 1991 to get the name; otherwise it is used as the name directly. 1992 If absent, the name of the directory containing the @filepath{info.rkt} 1993 file is used as the name.} 1994 @item{@racket['white-on-black-base?]: must be a boolean indicating if this 1995 color-scheme is based on an inverted color scheme. If absent, it 1996 is @racket[#f].} 1997 @item{@racket['example]: must be a string and is used in the preferences dialog 1998 to show an example of the color scheme. If absent, the string used in 1999 the ``Classic'' color scheme is used.} 2000 @item{@racket['colors]: must be a non-empty list whose first position 2001 is a symbol, naming a color or style. The rest of the elements describe 2002 the style or color. In either case, an element may be a vector describing 2003 a color, see below. 2004 If the name corresponds to a style, then the list may also contain 2005 2006 @itemlist[@item{Symbols @racket['bold], @racket['italic], 2007 or @racket['underline], changing the font style 2008 or underline status, or} 2009 @item{A prefab struct @racket[`#s(background ,_vec)], 2010 specifying the background color where 2011 @racket[_vec] is a vector describing a color.}] 2012 2013 A vector describing a color is either a vector of three bytes describing 2014 the red, green and blue component of a non-transparent color, 2015 or a vector of three bytes followed by a real number between 2016 @racket[0] and @racket[1], giving the alpha value in addition to color 2017 components. In other words, a vector satisfying the following contract 2018 describes a color: 2019 2020 @racketblock[ 2021 (or/c (vector/c byte? byte? byte? #:flat? #t) 2022 (vector/c byte? byte? byte? (between/c 0.0 1.0) #:flat? #t)) 2023 ] 2024 2025 Examples: 2026 2027 @racketblock[ 2028 '((framework:syntax-color:scheme:symbol 2029 #(0 0 0)) 2030 (framework:syntax-color:scheme:comment 2031 #(#xC2 #x74 #x1F) italic) 2032 (framework:syntax-color:scheme:error 2033 bold underline #(#xFF #x00 #x00)) 2034 (plt:htdp:test-coverage-off 2035 #(#xFF #xA5 #x00) 2036 #s(background #(#x00 #x00 #x00)))) 2037 ] 2038 }] 2039 2040 The names of the colors and styles are extensible; new ones can be added by calling 2041 @racket[color-prefs:add-color-scheme-entry]. When 2042 @racket[color-prefs:register-info-based-color-schemes] 2043 is called, it logs the active set of color names and style names to the @tt{color-scheme} 2044 logger at the info level. So, for example, starting up DrRacket like this: 2045 @tt{racket -W info@"@"color-scheme -l drracket} will print out the styles used in your 2046 version of DrRacket.}) 2047 2048 (proc-doc/names 2049 color-prefs:set-current-color-scheme 2050 (-> symbol? void?) 2051 (name) 2052 @{Sets 2053 the current color scheme to the scheme named @racket[name], 2054 if @racket[name] is @racket[color-prefs:known-color-scheme-name?]. 2055 Otherwise, does nothing.}) 2056 2057 (proc-doc 2058 color-prefs:get-current-color-scheme-name 2059 (-> color-prefs:color-scheme-style-name?) 2060 @{Returns the current color scheme's name.}) 2061 2062 (proc-doc/names 2063 color-prefs:known-color-scheme-name? 2064 (-> any/c boolean?) 2065 (name) 2066 @{Returns @racket[#t] if the input is a @racket[symbol?] that names 2067 a color or style that is part of the current color scheme. 2068 2069 In order to return @racket[#t], @racket[name] must have been 2070 passed as the first argument to @racket[color-prefs:add-color-scheme-entry].}) 2071 2072 (proc-doc/names 2073 color-prefs:color-scheme-style-name? 2074 (-> any/c boolean?) 2075 (name) 2076 @{Returns @racket[#t] if @racket[name] is a known color scheme name, 2077 and is connected to a style. 2078 2079 In order to return @racket[#t], @racket[name] must have been 2080 passed as the first argument to @racket[color-prefs:add-color-scheme-entry] 2081 and the @racket[#:style] argument must have also been passed.}) 2082 2083 (proc-doc/names 2084 color-prefs:color-scheme-color-name? 2085 (-> any/c boolean?) 2086 (name) 2087 @{Returns @racket[#t] if @racket[name] is a known color scheme name, 2088 and is connected to a color. 2089 2090 In order to return @racket[#t], @racket[name] must have been 2091 passed as the first argument to @racket[color-prefs:add-color-scheme-entry] 2092 and the @racket[#:style] argument must have also been omitted or be @racket[#f].}) 2093 2094 (proc-doc 2095 color-prefs:lookup-in-color-scheme 2096 (->i ([name color-prefs:known-color-scheme-name?]) 2097 () 2098 [result (name) 2099 (if (color-prefs:color-scheme-style-name? name) 2100 (is-a?/c style-delta%) 2101 (is-a?/c color%))]) 2102 @{Returns the current style delta or color associated with @racket[name].}) 2103 2104 (proc-doc 2105 color-prefs:set-in-color-scheme 2106 (->i ([name color-prefs:known-color-scheme-name?] 2107 [new-val (name) 2108 (if (color-prefs:color-scheme-style-name? name) 2109 (is-a?/c style-delta%) 2110 (is-a?/c color%))]) 2111 () 2112 [result void?]) 2113 @{Updates the current color or style delta associated with 2114 @racket[name] in the current color scheme.}) 2115 2116 (proc-doc 2117 color-prefs:register-color-scheme-entry-change-callback 2118 (->i ([name color-prefs:known-color-scheme-name?] 2119 [fn (name) 2120 (-> (if (color-prefs:color-scheme-style-name? name) 2121 (is-a?/c style-delta%) 2122 (is-a?/c color%)) 2123 any)]) 2124 ([weak? boolean?]) 2125 [result void?]) 2126 (#f) 2127 @{Registers a callback that is invoked whenever the color mapped by 2128 @racket[name] changes. Changes may happen due to calls to 2129 @racket[color-prefs:set-in-color-scheme] or due to calls to 2130 @racket[color-prefs:set-current-color-scheme]. 2131 2132 If @racket[weak?] is @racket[#t], the @racket[fn] argument is held 2133 onto weakly; otherwise it is held onto strongly.}) 2134 2135 (proc-doc 2136 color-prefs:get-color-scheme-names 2137 (-> (values set? set?)) 2138 @{Returns two sets; the first is the known color scheme names that are just colors 2139 and the second is the known color scheme names that are styles. 2140 2141 These are all of the names that have been passed to @racket[color-prefs:add-color-scheme-entry].}) 2142 ) 2143 2144 2145 (define-syntax (racket:-reprovides stx) 2146 #`(provide 2147 (rename-out #,@(for/list ([suffix (in-list racket:ids)]) 2148 (define rkt (string->symbol (format "racket:~a" suffix))) 2149 (define scm (string->symbol (format "scheme:~a" suffix))) 2150 #`[#,rkt #,scm])))) 2151 (racket:-reprovides)