doc/html/ref/synth-gui.html

   1 <!-- Copyright (C) 2003 Red Hat, Inc.                                -->
   2 <!-- This material may be distributed only subject to the terms      -->
   3 <!-- and conditions set forth in the Open Publication License, v1.0  -->
   4 <!-- or later (the latest version is presently available at          -->
   5 <!-- http://www.opencontent.org/openpub/).                           -->
   6 <!-- Distribution of the work or derivative of the work in any       -->
   7 <!-- standard (paper) book form is prohibited unless prior           -->
   8 <!-- permission is obtained from the copyright holder.               -->
   9 <HTML
  10 ><HEAD
  11 ><TITLE
  12 >The I/O Auxiliary's User Interface</TITLE
  13 ><meta name="MSSmartTagsPreventParsing" content="TRUE">
  14 <META
  15 NAME="GENERATOR"
  16 CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+
  17 "><LINK
  18 REL="HOME"
  19 TITLE="eCos Reference Manual"
  20 HREF="ecos-ref.html"><LINK
  21 REL="UP"
  22 TITLE="eCos Synthetic Target"
  23 HREF="hal-synth-arch.html"><LINK
  24 REL="PREVIOUS"
  25 TITLE="Running a Synthetic Target Application"
  26 HREF="synth-running.html"><LINK
  27 REL="NEXT"
  28 TITLE="The Console Device"
  29 HREF="synth-console.html"></HEAD
  30 ><BODY
  31 CLASS="REFENTRY"
  32 BGCOLOR="#FFFFFF"
  33 TEXT="#000000"
  34 LINK="#0000FF"
  35 VLINK="#840084"
  36 ALINK="#0000FF"
  37 ><DIV
  38 CLASS="NAVHEADER"
  39 ><TABLE
  40 SUMMARY="Header navigation table"
  41 WIDTH="100%"
  42 BORDER="0"
  43 CELLPADDING="0"
  44 CELLSPACING="0"
  45 ><TR
  46 ><TH
  47 COLSPAN="3"
  48 ALIGN="center"
  49 >eCos Reference Manual</TH
  50 ></TR
  51 ><TR
  52 ><TD
  53 WIDTH="10%"
  54 ALIGN="left"
  55 VALIGN="bottom"
  56 ><A
  57 HREF="synth-running.html"
  58 ACCESSKEY="P"
  59 >Prev</A
  60 ></TD
  61 ><TD
  62 WIDTH="80%"
  63 ALIGN="center"
  64 VALIGN="bottom"
  65 ></TD
  66 ><TD
  67 WIDTH="10%"
  68 ALIGN="right"
  69 VALIGN="bottom"
  70 ><A
  71 HREF="synth-console.html"
  72 ACCESSKEY="N"
  73 >Next</A
  74 ></TD
  75 ></TR
  76 ></TABLE
  77 ><HR
  78 ALIGN="LEFT"
  79 WIDTH="100%"></DIV
  80 ><H1
  81 ><A
  82 NAME="SYNTH-GUI">The I/O Auxiliary's User Interface</H1
  83 ><DIV
  84 CLASS="REFNAMEDIV"
  85 ><A
  86 NAME="AEN17960"
  87 ></A
  88 ><H2
  89 >Name</H2
  90 >User Interface&nbsp;--&nbsp;Controlling the I/O Auxiliary</DIV
  91 ><DIV
  92 CLASS="REFSECT1"
  93 ><A
  94 NAME="SYNTH-GUI-DESCRIPTION"
  95 ></A
  96 ><H2
  97 >Description</H2
  98 ><P
  99 >The synthetic target auxiliary is designed to support both extensions
 100 and user customization. Support for the desired devices is dynamically
 101 loaded, and each device can extend the user interface. For example it
 102 is possible for a device to add menu options, place new buttons on the
 103 toolbar, create its own sub-window within the overall layout, or even
 104 create entire new toplevel windows. These subwindows or toplevels
 105 could show graphs of activity such as interrupts or packets being
 106 transferred. They could also allow users to interact with the eCos
 107 application, for example by showing a number of buttons which will be
 108 mapped on to digital inputs in the eCos application. Different
 109 applications will have their own I/O requirements, changing the
 110 host-side support files that get loaded and that may modify the user
 111 interface. The I/O auxiliary also reads in user configuration scripts
 112 which can enhance the interface in the same way. Therefore the exact
 113 user interface will depend on the user and on the eCos application
 114 being run. However the overall layout is likely to remain the same.
 115     </P
 116 ><DIV
 117 CLASS="INFORMALFIGURE"
 118 ><A
 119 NAME="AEN17966"><P
 120 ></P
 121 ><DIV
 122 CLASS="MEDIAOBJECT"
 123 ><P
 124 ><IMG
 125 SRC="screen_main.png"
 126 ALIGN="CENTER"></P
 127 ></DIV
 128 ><P
 129 ></P
 130 ></DIV
 131 ><P
 132 >The title bar identifies the window as belonging to an eCos synthetic
 133 target application and lists both the application name and its process
 134 id. The latter is especially useful if the application was started
 135 directly from a shell prompt and the user now wants to attach a gdb
 136 session. The window has a conventional menu bar with the usual
 137 entries, plus a toolbar with buttons for common operations such as cut
 138 and paste. Balloon help is supported.
 139     </P
 140 ><P
 141 >There is a central <A
 142 HREF="synth-gui.html#SYNTH-GUI-TEXT"
 143 >text window</A
 144 >,
 145 possibly surrounded by various sub-windows for various devices. For
 146 example there could be a row of emulated LED's above the text window,
 147 and monitors of ethernet traffic and interrupt activity on the right.
 148 At the bottom of the window is a status line, including a small
 149 animation that shows whether or not the eCos application is still
 150 running.
 151     </P
 152 ></DIV
 153 ><DIV
 154 CLASS="REFSECT1"
 155 ><A
 156 NAME="SYNTH-GUI-MENUS"
 157 ></A
 158 ><H2
 159 >Menus and the Toolbar</H2
 160 ><P
 161 >Usually there will be four menus on the menu bar:
 162 <SPAN
 163 CLASS="GUIMENU"
 164 >File</SPAN
 165 >, <SPAN
 166 CLASS="GUIMENU"
 167 >Edit</SPAN
 168 >,
 169 <SPAN
 170 CLASS="GUIMENU"
 171 >View</SPAN
 172 > and <SPAN
 173 CLASS="GUIMENU"
 174 >Help</SPAN
 175 >.
 176     </P
 177 ><DIV
 178 CLASS="INFORMALFIGURE"
 179 ><A
 180 NAME="AEN17980"><P
 181 ></P
 182 ><DIV
 183 CLASS="MEDIAOBJECT"
 184 ><P
 185 ><IMG
 186 SRC="menu_file.png"
 187 ALIGN="CENTER"></P
 188 ></DIV
 189 ><P
 190 ></P
 191 ></DIV
 192 ><P
 193 >On the <SPAN
 194 CLASS="GUIMENU"
 195 >File</SPAN
 196 > menu there are three entries related to
 197 saving the current contents of the central text window.
 198 <SPAN
 199 CLASS="GUIMENUITEM"
 200 >Save</SPAN
 201 > is used to save the currently visible
 202 contents of the text window. Any text that is hidden because of
 203 filters will not be written to the savefile. If there has been a
 204 previous <SPAN
 205 CLASS="GUIMENUITEM"
 206 >Save</SPAN
 207 > or <SPAN
 208 CLASS="GUIMENUITEM"
 209 >Save
 210 As</SPAN
 211 > operation then the existing savefile will be re-used,
 212 otherwise the user will be asked to select a suitable file.
 213 <SPAN
 214 CLASS="GUIMENUITEM"
 215 >Save As</SPAN
 216 > also saves just the currently
 217 visible contents but will always prompt the user for a filename.
 218 <SPAN
 219 CLASS="GUIMENUITEM"
 220 >Save All</SPAN
 221 > can be used to save the full
 222 contents of the text window, including any text that is currently
 223 hidden. It will always prompt for a new filename, to avoid confusion
 224 with partial savefiles.
 225     </P
 226 ><P
 227 >Usually the eCos application will be run from inside gdb or from a
 228 shell prompt. Killing off the application while it is being debugged
 229 in a gdb session is not a good idea, it would be better to use gdb's
 230 own <B
 231 CLASS="COMMAND"
 232 >kill</B
 233 > command. Alternatively the eCos
 234 application itself can use the <TT
 235 CLASS="FUNCTION"
 236 >CYG_TEST_EXIT</TT
 237 > or
 238 <TT
 239 CLASS="FILENAME"
 240 >cyg_hal_sys_exit</TT
 241 > functionality. However it is
 242 possible to terminate the application from the I/O auxiliary using
 243 <SPAN
 244 CLASS="GUIMENUITEM"
 245 >Kill eCos</SPAN
 246 >. A clean shutdown will be
 247 attempted, but that can fail if the application is currently halted
 248 inside gdb or if it has crashed completely. As a last resort
 249 <TT
 250 CLASS="CONSTANT"
 251 >SIGKILL</TT
 252 > will be used.
 253     </P
 254 ><P
 255 >When operating in graphical mode the I/O auxiliary will normally
 256 continue to run even after the eCos application has exited. This
 257 allows the user to examine the last few lines of output, and perhaps
 258 perform actions such as saving the output to a file. The
 259 <SPAN
 260 CLASS="GUIMENUITEM"
 261 >Exit</SPAN
 262 > menu item can be used to shut down the
 263 auxiliary. Note that this behaviour can be changed with command line
 264 arguments <A
 265 HREF="synth-running.html#SYNTH-RUNNING-ARGUMENTS"
 266 ><TT
 267 CLASS="OPTION"
 268 >--exit</TT
 269 ></A
 270 > and
 271 <A
 272 HREF="synth-running.html#SYNTH-RUNNING-ARGUMENTS"
 273 ><TT
 274 CLASS="OPTION"
 275 >--no-exit</TT
 276 ></A
 277 >.
 278     </P
 279 ><P
 280 >If <SPAN
 281 CLASS="GUIMENUITEM"
 282 >Exit</SPAN
 283 > is used while the eCos application
 284 is still running then the I/O auxiliary will first attempt to
 285 terminate the application cleanly, and then exit.
 286     </P
 287 ><DIV
 288 CLASS="INFORMALFIGURE"
 289 ><A
 290 NAME="AEN18005"><P
 291 ></P
 292 ><DIV
 293 CLASS="MEDIAOBJECT"
 294 ><P
 295 ><IMG
 296 SRC="menu_edit.png"
 297 ALIGN="CENTER"></P
 298 ></DIV
 299 ><P
 300 ></P
 301 ></DIV
 302 ><P
 303 >The <SPAN
 304 CLASS="GUIMENU"
 305 >Edit</SPAN
 306 > menu contains the usual entries for
 307 text manipulation: <SPAN
 308 CLASS="GUIMENUITEM"
 309 >Cut</SPAN
 310 >,
 311 <SPAN
 312 CLASS="GUIMENUITEM"
 313 >Copy</SPAN
 314 >, <SPAN
 315 CLASS="GUIMENUITEM"
 316 >Paste</SPAN
 317 >,
 318 <SPAN
 319 CLASS="GUIMENUITEM"
 320 >Clear</SPAN
 321 > and <SPAN
 322 CLASS="GUIMENUITEM"
 323 >Select
 324 All</SPAN
 325 >. These all operate on the central text window. By
 326 default this window cannot be edited so the cut, paste and clear
 327 operations are disabled. If the user wants to edit the contents of the
 328 text window then the <SPAN
 329 CLASS="GUIMENUITEM"
 330 >Read Only</SPAN
 331 > checkbutton
 332 should be toggled.
 333     </P
 334 ><P
 335 >The <SPAN
 336 CLASS="GUIMENUITEM"
 337 >Preferences</SPAN
 338 > menu item brings up a
 339 miscellaneous preferences dialog. One of the preferences relates to
 340 online help: the I/O auxiliary does not currently have a built-in html
 341 viewer; instead it will execute an external browser of some sort. With
 342 the example settings shown, the I/O auxiliary will first attempt to
 343 interact with an existing mozilla session. If that fails it will try
 344 to run a new mozilla instance, or as a last result use the Gnome help
 345 viewer.
 346     </P
 347 ><DIV
 348 CLASS="INFORMALFIGURE"
 349 ><A
 350 NAME="AEN18019"><P
 351 ></P
 352 ><DIV
 353 CLASS="MEDIAOBJECT"
 354 ><P
 355 ><IMG
 356 SRC="preferences.png"
 357 ALIGN="CENTER"></P
 358 ></DIV
 359 ><P
 360 ></P
 361 ></DIV
 362 ><P
 363 >The <SPAN
 364 CLASS="GUIMENU"
 365 >View</SPAN
 366 > menu contains the <SPAN
 367 CLASS="GUIMENUITEM"
 368 >System
 369 Filters</SPAN
 370 > entry, used to edit the settings for the current
 371 <A
 372 HREF="synth-gui.html#SYNTH-GUI-TEXT"
 373 >filters</A
 374 >.
 375     </P
 376 ><DIV
 377 CLASS="INFORMALFIGURE"
 378 ><A
 379 NAME="AEN18027"><P
 380 ></P
 381 ><DIV
 382 CLASS="MEDIAOBJECT"
 383 ><P
 384 ><IMG
 385 SRC="menu_view.png"
 386 ALIGN="CENTER"></P
 387 ></DIV
 388 ><P
 389 ></P
 390 ></DIV
 391 ><P
 392 >The <SPAN
 393 CLASS="GUIMENU"
 394 >Help</SPAN
 395 > menu can be used to activate online help
 396 for eCos generally, for the synthetic target as a whole, and for
 397 specific devices supported by the generic target. The Preferences
 398 dialog can be used to select the browser that will be used.
 399     </P
 400 ><DIV
 401 CLASS="INFORMALFIGURE"
 402 ><A
 403 NAME="AEN18033"><P
 404 ></P
 405 ><DIV
 406 CLASS="MEDIAOBJECT"
 407 ><P
 408 ><IMG
 409 SRC="menu_help.png"
 410 ALIGN="CENTER"></P
 411 ></DIV
 412 ><P
 413 ></P
 414 ></DIV
 415 ><DIV
 416 CLASS="NOTE"
 417 ><BLOCKQUOTE
 418 CLASS="NOTE"
 419 ><P
 420 ><B
 421 >Note: </B
 422 >At the time of writing there is no well-defined toplevel index file
 423 for all eCos documentation. Hence the relevant menu item is disabled.
 424 Documentation for the synthetic target and the supported devices
 425 is stored as part of the package itself so can usually be found fairly
 426 easily. It may be necessary to set the <TT
 427 CLASS="ENVAR"
 428 >ECOS_REPOSITORY</TT
 429 >
 430 environment variable.
 431     </P
 432 ></BLOCKQUOTE
 433 ></DIV
 434 ></DIV
 435 ><DIV
 436 CLASS="REFSECT1"
 437 ><A
 438 NAME="SYNTH-GUI-TEXT"
 439 ></A
 440 ><H2
 441 >The Main Text Window</H2
 442 ><P
 443 >The central text window holds the console output from the eCos
 444 application: the screen shot above shows DHCP initialization data from
 445 the TCP/IP stack, and some output from the <TT
 446 CLASS="FUNCTION"
 447 >main</TT
 448 >
 449 thread at the bottom. Some devices can insert text of their own, for
 450 example the ethernet device support can be configured to show details
 451 of incoming and outgoing packets. Mixing the output from the eCos
 452 application and the various devices can make it easier to understand
 453 the order in which events occur.
 454     </P
 455 ><P
 456 >The appearance of text from different sources can be controlled by
 457 means of filters, and it is also possible to hide some of the text.
 458 For example, if tracing is enabled in the eCos configuration then the
 459 trace output can be given its own colour scheme, making it stand out
 460 from the rest of the output. In addition the trace output is generally
 461 voluminous so it can be hidden by default, made visible only to find
 462 out more about what was happening when a particular problem occurred.
 463 Similarly the ethernet device support can output details of the
 464 various packets being transferred, and using a different background
 465 colour for this output again makes it easier to distinguish from
 466 console output.
 467     </P
 468 ><P
 469 >The default appearance for most filters is controlled via the
 470 <A
 471 HREF="synth-running.html#SYNTH-RUNNING-TDF"
 472 >target definition file</A
 473 >. An
 474 example entry might be:
 475     </P
 476 ><TABLE
 477 BORDER="5"
 478 BGCOLOR="#E0E0F0"
 479 WIDTH="70%"
 480 ><TR
 481 ><TD
 482 ><PRE
 483 CLASS="PROGRAMLISTING"
 484 >  filter trace {^TRACE:.*} -foreground HotPink1 -hide 1</PRE
 485 ></TD
 486 ></TR
 487 ></TABLE
 488 ><P
 489 >The various colours and the hide flag for each filter can be changed
 490 at run-time, using the <SPAN
 491 CLASS="GUIMENUITEM"
 492 >System Filters</SPAN
 493 > item
 494 on the <SPAN
 495 CLASS="GUIMENU"
 496 >View</SPAN
 497 > menu. This will bring up a dialog like
 498 the following:
 499     </P
 500 ><DIV
 501 CLASS="INFORMALFIGURE"
 502 ><A
 503 NAME="AEN18051"><P
 504 ></P
 505 ><DIV
 506 CLASS="MEDIAOBJECT"
 507 ><P
 508 ><IMG
 509 SRC="filters.png"
 510 ALIGN="CENTER"></P
 511 ></DIV
 512 ><P
 513 ></P
 514 ></DIV
 515 ><P
 516 >It should be noted that the text window is line-oriented, not
 517 character-oriented. If an eCos application sends a partial line of
 518 text then that will remain buffered until a newline character is
 519 received, rather than being displayed immediately. This avoids
 520 confusion when there is concurrent output from several sources.
 521     </P
 522 ><P
 523 >By default the text window is read-only. This means it will not allow
 524 cut, paste and clear operations, and keyboard input will be ignored.
 525 The <SPAN
 526 CLASS="GUIMENU"
 527 >Edit</SPAN
 528 > menu has a checkbutton <SPAN
 529 CLASS="GUIMENUITEM"
 530 >Read
 531 Only</SPAN
 532 > which can be toggled to allow write operations. For
 533 example, a user could type in a reminder of what was happening at this
 534 time, or paste in part of a gdb session. Such keyboard input does not
 535 get forwarded to the eCos application: if the latter requires keyboard
 536 input then that should happen via a separate keyboard device.
 537     </P
 538 ></DIV
 539 ><DIV
 540 CLASS="REFSECT1"
 541 ><A
 542 NAME="SYNTH-GUI-LAYOUT"
 543 ></A
 544 ><H2
 545 >Positioning Optional Windows</H2
 546 ><P
 547 >Some devices may create their own subwindows, for example to monitor
 548 ethernet traffic or to provide additional I/O facilities such as
 549 emulated LED's or buttons. Usually the target definition file can be
 550 used to control the <A
 551 HREF="synth-gui.html#SYNTH-GUI-LAYOUT"
 552 >layout</A
 553 > of
 554 these windows. This requires an understanding of the overall layout of
 555 the display.
 556     </P
 557 ><DIV
 558 CLASS="INFORMALFIGURE"
 559 ><A
 560 NAME="AEN18063"><P
 561 ></P
 562 ><DIV
 563 CLASS="MEDIAOBJECT"
 564 ><P
 565 ><IMG
 566 SRC="layout.png"
 567 ALIGN="CENTER"></P
 568 ></DIV
 569 ><P
 570 ></P
 571 ></DIV
 572 ><P
 573 >Subwindows are generally packed in one of eight frames surrounding the
 574 central text window: <TT
 575 CLASS="VARNAME"
 576 >.main.nw</TT
 577 >,
 578 <TT
 579 CLASS="VARNAME"
 580 >.main.n</TT
 581 >, <TT
 582 CLASS="VARNAME"
 583 >.main.ne</TT
 584 >,
 585 <TT
 586 CLASS="VARNAME"
 587 >.main.w</TT
 588 >, <TT
 589 CLASS="VARNAME"
 590 >.main.e</TT
 591 >,
 592 <TT
 593 CLASS="VARNAME"
 594 >.main.sw</TT
 595 >, <TT
 596 CLASS="VARNAME"
 597 >.main.s</TT
 598 >, and
 599 <TT
 600 CLASS="VARNAME"
 601 >.main.se</TT
 602 >. To position a row of LED's above the text
 603 window and towards the left, a target definition file could contain an
 604 entry such as:
 605     </P
 606 ><TABLE
 607 BORDER="5"
 608 BGCOLOR="#E0E0F0"
 609 WIDTH="70%"
 610 ><TR
 611 ><TD
 612 ><PRE
 613 CLASS="PROGRAMLISTING"
 614 >synth_device led {
 615     pack -in .main.n -side left
 616     &#8230;
 617 }</PRE
 618 ></TD
 619 ></TR
 620 ></TABLE
 621 ><P
 622 >Similarly, to put a traffic monitor window on the right of the text
 623 window would involve something like:
 624     </P
 625 ><TABLE
 626 BORDER="5"
 627 BGCOLOR="#E0E0F0"
 628 WIDTH="70%"
 629 ><TR
 630 ><TD
 631 ><PRE
 632 CLASS="PROGRAMLISTING"
 633 >    &#8230;
 634     monitor_pack -in .main.e -side bottom
 635     &#8230;</PRE
 636 ></TD
 637 ></TR
 638 ></TABLE
 639 ><P
 640 >Often it will be sufficient to specify a container frame and one of
 641 <TT
 642 CLASS="CONSTANT"
 643 >left</TT
 644 >, <TT
 645 CLASS="CONSTANT"
 646 >right</TT
 647 >,
 648 <TT
 649 CLASS="CONSTANT"
 650 >top</TT
 651 > or <TT
 652 CLASS="CONSTANT"
 653 >bottom</TT
 654 >. Full control
 655 over the positioning requires an understanding of Tcl/Tk and in
 656 particular the packing algorithm, and an appropriate reference work
 657 should be consulted.
 658     </P
 659 ></DIV
 660 ><DIV
 661 CLASS="REFSECT1"
 662 ><A
 663 NAME="SYNTH-GUI-GLOBAL-CONFIG"
 664 ></A
 665 ><H2
 666 >Global Settings</H2
 667 ><DIV
 668 CLASS="NOTE"
 669 ><BLOCKQUOTE
 670 CLASS="NOTE"
 671 ><P
 672 ><B
 673 >Note: </B
 674 >This section still to be written - it should document the interaction
 675 between X resources and ecosynth, and how users can control settings
 676 such as the main foreground and background colours.
 677     </P
 678 ></BLOCKQUOTE
 679 ></DIV
 680 ></DIV
 681 ><DIV
 682 CLASS="NAVFOOTER"
 683 ><HR
 684 ALIGN="LEFT"
 685 WIDTH="100%"><TABLE
 686 SUMMARY="Footer navigation table"
 687 WIDTH="100%"
 688 BORDER="0"
 689 CELLPADDING="0"
 690 CELLSPACING="0"
 691 ><TR
 692 ><TD
 693 WIDTH="33%"
 694 ALIGN="left"
 695 VALIGN="top"
 696 ><A
 697 HREF="synth-running.html"
 698 ACCESSKEY="P"
 699 >Prev</A
 700 ></TD
 701 ><TD
 702 WIDTH="34%"
 703 ALIGN="center"
 704 VALIGN="top"
 705 ><A
 706 HREF="ecos-ref.html"
 707 ACCESSKEY="H"
 708 >Home</A
 709 ></TD
 710 ><TD
 711 WIDTH="33%"
 712 ALIGN="right"
 713 VALIGN="top"
 714 ><A
 715 HREF="synth-console.html"
 716 ACCESSKEY="N"
 717 >Next</A
 718 ></TD
 719 ></TR
 720 ><TR
 721 ><TD
 722 WIDTH="33%"
 723 ALIGN="left"
 724 VALIGN="top"
 725 >Running a Synthetic Target Application</TD
 726 ><TD
 727 WIDTH="34%"
 728 ALIGN="center"
 729 VALIGN="top"
 730 ><A
 731 HREF="hal-synth-arch.html"
 732 ACCESSKEY="U"
 733 >Up</A
 734 ></TD
 735 ><TD
 736 WIDTH="33%"
 737 ALIGN="right"
 738 VALIGN="top"
 739 >The Console Device</TD
 740 ></TR
 741 ></TABLE
 742 ></DIV
 743 ></BODY
 744 ></HTML
 745 >