AT&T Home | AT&T Labs | Research
AT&T Labs, Inc. - Research

The Yoix® Scripting Language

Home | What's New | Grammar | Documentation | Download | License | YChart | YDAT | YWAIT | Byzgraf | FAQs

Yoix / General YChart Usage Help

In the following, any mention of a drop-down menu refers to a menu implemented using a JComboBox. Also, Apple users should translate any reference to a CTRL modifer as a reference to the Apple command key, which is marked by the Unicode "Place of Interest Sign", namely the ⌘ character. This key is also sometimes referred to as the Apple key since on some keyboards it also has the Apple logo character, namely the  character, on it. For Apple users, pressing the left mouse button while holding the key marked CTRL acts just like a right mouse button press as regards pop-up menus, but this is platform dependent behavior that is not controlled by YChart.

Mouse Actions

The right mouse button applied over the chart itself will bring up a pop-up menu that provides fast access to many of the options available through the drop-down menu with the difference that the options selected through the pop-up menu only remain in effect for the next mouse action whereas options selected through the drop-down menu remain in effect for as long as the option remains selected in that menu. Also, when a puzzle chart is available, additional options appear in this pop-up menu that are specific to the puzzle chart.

Note that when the mouse cursor is over the drop-down menu at the lower-center of the screen, a pop-up menu setting the sort order of the drop-down menu is available in some cases.

The center mouse button will always allow one to reposition the chart by panning, i.e., draging, the chart.

The mouse button accepts modifiers and can be used to perform a number of functions:

  • Left button + No modifiers: The left mouse button without any modifiers can trigger several actions depending on where it is applied:
    • when applied in the chart itself, the specific action is determined by the current menu selection in the drop-down menu or the active pop-up menu selection, if any;
    • when applied over the magnifying glass icon at the lower-center-left of the screen, a slider pops up to allow adjustment of the chart zoom as the mouse cursor, with the left button still depressed, is dragged over the slider;
    • when applied over the blue, decimal number to the left of the magnifying glass icon, the zoom factor will toggle between its current value, which is indicated by those decimal numbers, and 1.00;
    • when applied over the compass rose at the lower-right of the screen, the chart will be moved left, right, up or down depending on which little triangle is pressed. When the center square is pressed the chart will toggle between its current position and being anchored of the selected cell or, when no cell is selected, on the anchor point of the chart (see the Anchor option described below as part of the Settings menu of the menubar). Note that this latter behavior also occurs when the right mouse button is applied over the aforementioned decimal number, namely the zoom factor.
  • Left button + CTRL modifier: when applied to a cell, toggles the selection state of that cell. Selecting a cell not only highlights the cell, but also populates several areas with information related to the selected cell:
    • right side of the split pane, if visible, populates with details relating to the selected cell;
    • the cell selection drop-down menu at the lower-center of the screen is set to the selected cell;
    • if available, the URL text field is populated with an appropriate URL where additional information related to the selected cell can be found. Incidentally, pressing the Open button to the right of that field should bring up a web browser displaying the page associated with that URL.
  • Left button + SHIFT modifier: when applied to a cell, it allows that cell to be moved (dragged) to a new location. At the same time, it highlights the original location of that cell.

Mouse Wheel

The mouse wheel works in many components and it is often the fastest way to do certain things:
  • when the mouse cursor is on the chart itself, the mouse wheel will zoom the chart in or out and wherever the mouse cursor happens to be located will remain fixed as the zoom occurs;
  • zooming occurs when the mouse cursor is over the magnifying glass icon or the zoom-scale label; in these cases, the fixed zoom point is the current anchor point (see the Anchor option described below as part of the Settings menu of the menubar);
  • when applied over a JComboBox, i.e., a drop-down menu, the mouse wheel will scroll through the available items in the menu. For example, over the middle drop-down menu, scrolling will cause each current menu item to select the associated cell and anchor the chart on that cell.
  • if the mouse wheel is rotated over any of the the middle drop-down menus while the SHIFT key is held then the selected items will be restricted to those that correspond to cells that have been moved.

Menu Options

Action Menu

The action menu is a drop-down menu located a the lower-left of the screen. Its options include:
  • Cell Copy: Allows a user to choose a cell and when chosen, the information in the cell is stored in the system clipboard buffer. The information is stored as individual lines of text in the following order:
    1. main, center label;
    2. top labels left to right, working down;
    3. bottom labels, left to right, working up.
  • Cell Drag and Drop (DnD): Allows a user to initiate a dragging action on a cell and drop any of its labels onto any appropriate recipient inside or outside the application.
  • Erase Mark: Allows a user to select a mark on the chart or cell and clear it, i.e., erase it (see mark cell and mark chart, below).
  • Mark Cell: Allows user to write, using the mouse, in a cell. Writing outside the cell is cropped. The result is a multi-segment line, i.e., a squiggle, with or without an arrowhead at its final point. Arrow mode can be toggled either through the Settings menu in the menubar or by pressing the ALT key while marking. Linux users may need to depress the ALT after the mouse motion has begun to avoid unintentionally triggering a window manager action. As far as YChart is concerned, the ALT key only really has an effect when the mouse button is released.
  • Mark Chart: Allows user to write, using the mouse, on the chart. Arrow mode can be toggled either through the Settings menu in the menubar or by pressing the ALT key while marking. See mark cell, above, for additional comments regarding arrow marking.
  • Move Cell: Allows a user to move and position a cell anywhere in the chart.
  • Pan: Allows a user to move the whole chart as a unit within the visible area.
  • Return Cell: Allows a user to return a moved cell to its original location. The original location is highlighted. A double-click on a moved cell will return it directly to its original location.
  • Select Cell: Allows a user to select a cell.

Selection Menu

The selection menu at the lower-center of the screen lists the cells. Selection from the menu causes the corresponding cell to be selected and vice versa. There can be up to three different selection menus on the same screen, each employing a different selection criterion.

Site Menu

This menu is visible when the URL field is visible. When there are several external sources available for additional information about a cell, this menu allows a particular site to be the source used when constructing the external source URL when cells are selected.

Pop-Up Chart Menu

The pop-up menu available on the chart contains the same options as the action menu plus the following options:
  • Erase All Cell Marks: Erases all cell markings, but leaves chart markings intact.
  • Erase All Chart Marks: Erases all chart markings, but leaves cell markings intact.
  • Return All Cells: Returns all cells to their original positions.
Also, when a puzzle chart is available, there is a sub-menu in the pop-up menu that contains the following additional entries:
  • Auto Check: Automatically marks a misplaced cell with a red "X" across the face of the cell as the cells are placed.
  • Check Chart: Runs a check of all the currently placed cells and marks the face of any misplaced cells with a red "X".
  • Clear Mistakes: Clears the red "X" from misplaced cells, but does not reposition them. This action clears all red "X" marks whether they resulted from an Auto Check or a Check Chart. mode.
  • Scatter the Cells: Resets the puzzle to its initial state, although the cell starting positions will be different from the last time since they are randomly placed.
  • Solve the Puzzle: moves all the puzzle pieces to their correct positions.

Menubar

There are several menubar menus. Of interest are:
  • Settings:
    • Anchor: A menu that can be used to disable cell anchoring, which means cells will not move when selected. It can also be used to set the anchoring of the chart so that the anchor point in the selected cell, or the anchor point of the chart if there is no selected cell, appears at one of the following locations in the viewer panel: top left, top, top right, left, center, right, bottom left, bottom and bottom right. The precise position of the anchor points are actually under the control of the YChart designer; the listed points are the defaults.
    • Show Column Labels: Toggles display of chart column labels, if any.
    • Show Row Labels: Toggles display of chart row labels, if any.
    • Show Chart Grid: Toggles display of the grid used when placing cells.
    • Show Find Panel: Toggles display of the find panel, which can also be toggled by using CTRL-F.
    • Hide Unselected Cell Labels: Arranges to hide all cell labels except for the ones that belong to the currently selected cell. We though this might occasionally be useful if the chart is being used as a teaching tool.
    • Terminate Marks With Arrow: Chart or cell marks added when this is selected are terminated with an arrow head.
  • Charts: Lists the charts that are available for loading into the viewer. There are also options for reloading the current chart and clearing the chart cache.
  • Colors: Lists the coloring schemes available for the current chart. In addition there is a reverse video option that essentially just toggles the background color between black and white.
  • Filters: This is an optional menu that, if present, contains items usually organized in sub-menus that represent a single filter and allow groups of cells to be selectively hidden. When there are several filters, cells are hidden unless they are selected by all the filters. Two special items named All On and All Off usually appear in filter sub-menus and can be used to apply the selection operation to all cells in the chart.

Find Panel

Display of the find panel can occur through a Settings menubar option or by using CTRL-F. The find panel can be used to search through the selection menu. If a match is found, that menu entry and the corresponding cell are selected, otherwise the search string is shown in red. A match occurs if search string is contained anywhere within a selection menu entry. There is an option to match upper/lower case letters and to search forwards and backwards.

Arrow Buttons

Certain YChart displays may have up and down arrow buttons to the right of the selection menu(s) at the lower-center of the screen. When present, these buttons allow one to step through cell selections. To clarify, visually, the transition from one selected cell to the next, an arrow is drawn from the previously selected cell to the newly selected cell and the chart is anchored (see the Anchor option described above as part of the Settings menu of the menubar) on the newly selected cell. The speed with which the chart is re-anchored and the duration that the arrow is displayed depends directly on how long the arrow button remains depressed.

In cases where the next cell to select may be ambiguous because it could be any of a set of cells, then the last cell that was selected, using any of the possible cell selection methods, in that set will be used. In such cases, a check mark may be used by the YChart designer to indicate which cell that will be.

Key Mappings

There are a number of key mappings provided as a convenient way to accomplish tasks. These mappings include:
  • CTRL-F: toggle find panel visibility
  • CTRL-G: find next matching cell (forward)
  • CTRL-SHIFT-G: find next matching cell (backward)
  • UP-ARROW: pan or scroll chart up by half a row
  • DOWN-ARROW: pan or scroll chart down by half a row
  • LEFT-ARROW: pan or scroll chart left by half a column
  • RIGHT-ARROW: pan or scroll chart right by half a column
  • PAGE-UP: pan or scroll chart up by the visible amount
  • PAGE-DOWN: pan or scroll chart down by the visible amount
  • SHIFT-PAGE-UP: pan or scroll chart left by the visible amount
  • SHIFT-PAGE-DOWN: pan or scroll chart right by the visible amount
  • CTRL-PAGE-UP: zoom chart out a bit
  • CTRL-PAGE-DOWN: zoom chart in a bit
  • HOME: toggle between anchoring the chart as a whole or anchoring on the selected cell (see Anchor)
  • END: toggle between current zoom factor and actual size (zoom factor of 1.0)

Command-Line Arguments

A standalone YChart application is invoked by any of the following three command-line calling sequences: 
   java [java_args] -jar yoix.jar [yoix_args] ychart.yx [ychart_args] ychart_script_file.yx

   yoix [yoix_args] ychart.yx [ychart_args] ychart_script_file.yx

   ychart [ychart_args] ychart_script_file.yx
The optional Java and Yoix command-line arguments are described elsewhere. The optional YChart arguments are:
  • -a ratio: Sets the cell aspect ratio as a non-negative floating-point number. Uninitialized by default.
  • -b border: Sets the cell border as a non-negative floating-point number. Uninitialized by default.
  • -f font: Sets the font used in the chart. The font is scaled to provide the different sized fonts used throughout the chart. The default is: Lucida-bold-12.
  • -m margin: Sets the cell margin as a non-negative floating-point number. Uninitialized by default.
  • (-|+)p: Do (+) or do not (-) pre-load the charts; only charts that have a non-zero preload field in their dictionaries can be pre-loaded. The default is to not pre-load any charts.
  • (-|+)r: Do (+) or do not (-) reverse the chart foreground and background colors. The default is to not reverse the colors.
  • -s separation: Sets the cell separation as a non-negative floating-point number. Uninitialized by default.
  • (-|+)u: Do (+) or do not (-) use the clipping path to suppress painting computations for cells outside the clip area. The default is to use the clipping path.
  • -w line-width: Sets the mark line-width as a non-negative floating-point number. The default is 1.5.
  • (-|+)y: Do (+) or do not (-) use the YChart module (yoix.ychart). A warning is written to the standard error stream if the module is not used. The default is to use the YChart module.
  • -B browser-command: The command to execute when opening a URL. The default is to attempt to determine the command automatically.
  • -P program: Sets the program name that is displayed in error messages and warnings. The default is: yoix.
  • -T frame-title: Sets the title used for the JFrame. The default is: Yoix® YChart.
  • (-|+)Y: Do (+) or do not (-) use the YChart module (yoix.ychart). No warning is written to the standard error stream if the module is not used. The default is to use the YChart module.

 

Yoix is a registered trademark of AT&T Inc.