Tab Strip, Menu & Tool Bars

The main content panel in Figure Composer's application window manages the set of currently open figures. While it looks much like a standard tabbed pane, in reality it is not. A narrow tab strip lies along the top of a panel containing the figure canvas, figure navigator, and property editor. The currently selected figure is loaded for display into these three components, and the currently selected tab -- which is highlighted by a steel blue gradient background -- displays the file name for that figure (if the figure has never been saved, the tab title reads "<New figure>" instead). Whenever you open a figure, a new tab is appended to the strip to represent that figure; the tab is selected, and the figure is loaded into the canvas, navigator, and property editor components. Similarly, when you click on an unselected tab, the currently displayed figure is unloaded, the clicked tab is selected, and the corresponding figure is loaded for display.

Figure Composer lets you open as many figures as you want. Once there are more open figure tabs than will fit horizontally in a single row along the tab strip, a small black downward arrow will appear after the last visible tab. Click on this arrow to raise a menu listing the file names for any hidden figure tabs. If you select any item from this "hidden tabs" menu, that tab appears in the tab strip and the corresponding figure is displayed; other tabs, of course, will be hidden. Any single tab may be closed by clicking the small "x" button that appear near the tab's right edge; if the figure has any unsaved changes, you will be prompted to save the figure before it is closed. Alternatively, right-click anywhere along the strip to raise a context menu that lets you close various subsets of the open tabs. This context menu is the same as the File|Close submenu -- see its description below.

You can also rearrange the order of the visible tabs in the strip. Simply drag any tab from its current location and drop it over a different spot along the strip; the drag gesture is animated, so it's fairly intuitive. If there are hidden tabs at the front of the list, drag past the left edge of the strip to scroll those hidden tabs into view; likewise, if there are hidden tabs at the tail end, drag past the strip's right edge to bring them into view.

Figure Composer's menu bar includes File, Edit and View menus. Many of the menu commands are also accessible via a toolbar docked along the top edge of the application frame window. The File menu includes commands that operate on an entire FypML figure file, as well as the typical "About", "Preferences", and "Exit" commands. Edit menu commands are used to insert, copy, paste, cut and delete graphic objects in the currently displayed figure. Finally, the View menu collects those actions that affect the current state of the Figure Canvas (zoom mode, display mode, rulers) and the visibility of selected components of the user interface. Selected commands in the Edit and View menus may also be invoked through a context menu raised when you right-click somewhere on the canvas.

A menu item (and its related toolbar button, if there is one) is disabled if the corresponding command action is not currently possible. If you're unsure what happens if you click a particular toolbar button or select a menu item, simply hold the mouse over that button or menu item and a brief explanatory tooltip will appear. The application toolbar can be configured in one of three states via the View|Toolbar menu: Hidden (if you prefer to use the menus instead), Compact (icons only; the default), or Full (labelled icons). Figure Composer remembers the toolbar state so that you do not have to set it each time you start the application.

Listed below are all of the action commands available in the File, Edit or View menus. If there is a keyboard shortcut for a particular menu item, that shortcut appears in parentheses after the item name. If the action is exposed as a push button or check box on the toolbar, the button's icon is also included.

Mac OS X specific

To conform to Apple's user interface guidelines, the menu bar is somewhat different in appearance on Mac OS X than what is described here. It is located along the top of the screen rather than inside the application window, and the Command key (rather than the Ctrl key) is used as the modifier key for most menu keyboard shortcuts. In addition, Figure Composer supports the Mac OS X application menu ("Apple" menu) items About, Preferences, and Quit; as a consequence, the equivalent commands File|About FigureComposer, File|Preferences, and File|Exit are omitted from Figure Composer's own menu bar when running on the Mac platform.

Any number of figures may be open at the same time in Figure Composer (but expect performance to degrade if too many are open!). A narrow tab strip control along the top of the main content panel, immediately above the Figure Canvas, displays a tab for each open figure (see the screenshot below). Once you confirm a selection in the file chooser dialog, Figure Composer opens a new tab on the tab strip, displaying the name of the corresponding file along with a FypML figure icon or a Matlab icon, depending on which type of figure file was selected. The new tab becomes the current tab, and the FypML figure loaded from the .fyp file (or imported from the Matlab FIG file) is displayed in the Figure Canvas. The source file is read and processed on a background thread to avoid "blocking" the user interface. If the file is very large/complex, or if the host machine is relatively slow, there may be a noticeable delay before the figure appears. In this case, the canvas will be blank, and the corresponding tab will read "LOADING..." as a cue that the figure is being loaded in the background.

[Note that if you happen to select a file that is already open in Figure Composer, the application does NOT open another copy of that figure; instead, it simply switches to the tab displaying the open figure.]

While the tab strip gives the main content area the appearance of a traditional tabbed pane, with a separate tab page for each figure, there are no such tab pages in reality. The tab strip lets the user choose which of the currently open figures is selected for display and editing within Figure Composer. Simply click on a tab to display the corresponding figure, i.e., to bring it to the front. To close the figure, click on the tab's "close" button if the figure has been modified -- in which case an asterisk (*) precedes the file name on the tab -- , you will be prompted to save the changes first.

While you can open compatible Matlab FIG files in Figure Composer, you cannot make changes to the figure and save it back to the FIG file. For this reason, when you initially open a FIG file, Figure Composer will mark it as modified to emphasize that the figure needs to be saved to the FypML file format. When you elect to save the figure, Figure Composer will raise the "Save as" dialog initialized to save the file in the same folder and with the same name as the original Matlab FIG file, but with the .fig extension replaced by .fyp. Once saved, the file name and icon are updated accordingly in the figure's tab.

The ability to open compatible Matlab FIG files was first formally introduced in Version 4.3.0. This feature is the most convenient and powerful conduit for getting data prepared and analyzed in Matlab into a Figure Composer FypML figure. Of course, not every Matlab figure can be converted to FypML, since Matlab offers a myriad of specialized plots and other features not supported in FypML. If a FIG file cannot be converted, then it will fail to load in Figure Composer. For a further discussion on translating Matlab figures to FypML, see the description of the utility function matfig2fyp(), which performs the same conversion on an open figure in the Matlab environment.

• • Current figure. This has the same effect as clicking the "x" button on the currently selected figure tab.

  • All figures.  All open tabs are closed, leaving a single tab displaying a brand-new figure.

  • All visible figures. This will close all the figures exposed in visible tabs.

  • All hidden figures. Any figures not exposed in the tab strip (listed in the "hidden tab" pop-up menu instead) will be closed.

  • All except current figure.

  • All left of current figure. Every figure tab to the left of the currently selected tab will be closed (including any hidden tabs).

  • All right of current figure. Every figure tab to the right of the current tab will be closed (including any hidden tabs).

  • All unmodified figures.

If any tab to be closed contains a modified figure, Figure Composer will ask you whether or not you want to save the changes prior to closing. You'll have the options to "Save all" or "Save None" -- so that you don't have to repeat yourself for each individual figure that needs to be saved. Of course, if you choose to save any modified figure that has never been saved to file, the application will ask you for a destination path.

Observe that a data presentation node is highlighted by a translucent blue rectangle in each figure. The title of that presentation node, plus the ID and data format of the underlying raw data set, are listed beneath the corresponding figure canvas. You can use the mouse to highlight a different data node in each figure. However, if the presentation nodes overlap significantly, you may prefer to use the green arrow buttons to scroll through the nodes (only data presentation nodes can be highlighted, since the focus here is on data).

Once you've selected the desired source and target nodes in each figure, press the Inject >> button to inject the underlying raw data set from the presentation node highlighted in the source figure into the target node in the destination figure. The destination figure will be redrawn to reflect the change. Remember that what you're copying and pasting is the underlying raw data set, NOT the presentation node itself. Thus, you will not change how the data is rendered in the target figure -- except to the extent that the raw data itself has changed.

Note that the Inject button will be disabled if the target presentation node does not support the format of the source data set (you can't inject raster1d data into a Heat Map node, for instance).

Repeat these steps to inject all of the data you need. If you need to inject data located in several different figure files, simply click the Change... button to change the source figure file. Once you're satisfied with your revised figure, click OK to save the changes and extinguish the dialog. Alternatively, you can Start Over or Cancel if you're not happy with the end result.

Use case. The File|Inject Data dialog may not be very useful when you're constructing a new figure from scratch. However, suppose you've spent several hours designing a complex, carefully formatted figure displaying many different data sets. Suppose further that this finished figure is based on the content of several rough-and-ready Matlab figures that your analysis code generates automatically. Then you realize you made a mistake in your analysis that slightly alters much of the data. You adjust your code and regenerate the rough Matlab figures. In this case, rather than rebuilding the publication-ready FypML figure from scratch, use File|Inject Data to copy and paste the revised raw data from the Matlab source figures into the existing FypML figure.

If you only need to inject one or two data sets, then it may be just as easy to open both source and destination figures in Figure Composer and use the Extract/Inject raw data commands from the Edit menu. These are discussed later in the chapter.

Figure Composer employs a custom Postscript generator to export a figure as an EPS file, rather than rely on Java native services that vectorize Java2D graphics into Postscript form. Figure Composer-generated EPS files use some Level 2 language features and conform to Adobe's Document Structuring Conventions, 3.0.

Authors should be mindful that the EPS file generated by the Export command does not replicate the display fonts used to render the figure onscreen. Postscript font support is a difficult issue, given the plethora of screen and printer fonts in existence. All TrueType fonts on the system may be downloaded onto Postscript printers that are Level 2 or higher. However, font downloading is an arduous undertaking. To avoid this complication, all FypML graphic nodes specify both a screen font and a Postscript font. The set of supported Postscript fonts is limited to Latin typefaces from the well-known and well-supported "Standard 35" set: Times, Courier, Helvetica, Helvetica Narrow, Avant Garde, Bookman, New Century Schoolbook, and Palatino. Figure Composer's Postscript generator assumes that all of these font families will be available -- in plain, bold, italic, and bold-italic faces -- on any Postscript interpreter to which the Postscript document is sent. By and large, this is a safe assumption for modern-day printers (and for applications that can read a Postscript document, like Adobe Illustrator). However, the "Standard 35" is not a requirement for any Postscript device, so it is always possible that a FC-generated PS file will not print or import properly. 

Unicode character support is another thorny issue. A Postscript font is limited to 255 characters at any one time, although the glyphs to which the character codes 0-255 map can be changed by altering the font's encoding vector. Even with re-encoding, the number of unique glyphs supported by the common Postscript fonts is much smaller than the set of glyphs supported onscreen. We've found that Adobe's pervasive Postscript 5 driver avoids the problem of font downloading and character support by rendering characters via character paths, consulting the font file for the necessary information. This again is beyond the scope of Figure Composer, and it has the added disadvantage of creating bloated Postscript files. The approach taken in FC is to restrict the allowed set of Unicode characters to a portion of two common character sets supported in most Postscript environments: the Standard Latin and Symbol character sets. FC-generated PS uses composite fonts (a Level 2 language feature) to cover all the possible characters in these sets. 

Similar issues apply when exporting to PDF. Figure Composer relies on the iText PDF library to export figures to the PDF format. Unlike PS, the exported PDF file will embed the host fonts used to render any text in the figure, so long as the font file is licensed as embeddable. Thus, there's a better chance that the exported PDF will exactly replicate the onscreen figure than the exported PS file. However, If the host font file is not embeddable or cannot be parsed by the iText library, then one of the standard 14 PDF Type 1 fonts (Courier + style variants, Times + style variant, Helvetica + style variants, Symbol) will be substituted for the problem font. Similarly, if the host font does not have a glyph for a given Unicode character in FC's supported character set, then that character will be rendered in one of the built-in fonts. (Note that iText supports most TrueType and OpenType fonts, plus Adobe Type 1 and Type 3 fonts. However, it cannot handle all fonts, particularly on Mac OS X.)

Support for the SVG export format was added in FC 5.4.2. The rendered SVG matches the original figure very well, but the file size tends to be significantly greater than PS/PDF output, and it is not as editable an export format. In particular, all text in the figure will be converted to filled glyph outlines in the SVG document (using the SVG path element), so it cannot be edited as text when imported into another program like PowerPoint. Translucency is preserved.

Postscript code. Results may vary with operating system, target printer, and so on. In our experience, the native conversion from Java2D to Postscript results in large (and slow) print jobs, particularly if there's a lot of text in the output. [Technically, this is because each character glyph is rendered individually as a complex closed path, rather than downloading the required font resource to the target printer and using that font directly.] On the other hand, text content in the printed output will more faithfully reflect what you see on screen ("what you see is what you get"). 

Alternatively, if the box is unchecked (the default), the application generates its own custom Postscript page descriptions, which (as mentioned earlier) are more compact and print much faster at the expense of accurate text reproduction. If you prefer the smaller, faster Figure Composer-generated PS output but want printouts to reflect what you see on the screen as accurately as possible, be sure to use only screen fonts that match the PS fonts supported by the application's Postscript generator (Times, Courier, Helvetica, Helvetica Narrow, AvantGarde, Bookman, Palatino, and New Century Schoolbook). 

To initiate the print job, press the OK button. Although the job is prepared and queued in a background thread, a modal "progress dialog" blocks the GUI and displays progress messages as the print job proceeds. Typical status messages include "Starting print job...", "Building page description...", and "Sending print data...." If the job completes successfully, the progress dialog disappears; if the job failed, dismiss the dialog at your leisure, after reading the error message displayed therein. While the print job is in progress, the dialog includes a Cancel button; if the job gets "stuck" for whatever reason, you may be able to cancel it by clicking this button. Whether or not the job is successfully removed from the print service's queue likely depends upon how well the native platform supports Java printing. However, hitting the Cancel button should at least kill the background thread and extinguish the progress dialog so that you may resume normal GUI interactions. 

The Print command only prints the currently selected figure. If you'd like to print all open figures in one go, use the Print all command instead. This command will send a print job to the target printer for each open figure; it can be a time-saver if you routinely work with multiple figures and want to print all of them.

Figure Composer maintains a private edit history for each open figure. A figure's edit history can be up to 30 operations long; once the history is full, the first (oldest) entry is discarded each time a new change is posted. Also, any undone changes at the end of the history must be discarded when a new change is posted; thus, the Redo command is always disabled after you make a change to the figure that does not involve Undo or Redo. Whenever a change is made that is irreversible, or if an Undo or Redo action should fail for some reason, the edit history is wiped clean, and both Undo and Redo commands are disabled.

Multi-node copy/cut, and paste. It is possible to copy or cut and paste a multiple-object selection in one command. Simply select the nodes of interest in the figure, and choose Edit|Copy or Edit|Cut. All of the selected nodes are cloned, and the list of copied nodes are placed in the graphic object clipboard. Observe that the Edit|Paste command's tooltip is modified to reflect the fact that the clipboard currently hold a list of two or more nodes instead of a single node: "Paste up to N nodes from clipboard." The paste action is also slightly different in the multi-node case. If you select a target parent node in the current figure or another figure and choose Edit|Paste (the command is never enabled when multiple nodes are selected), then all of the nodes in the clipboard will be inserted as children of the selected node, NOT as siblings. If any node in the clipboard cannot be added as a child of the selected node, it is ignored.

Use case. Since the Matlab FIG-to-FypML import feature was introduced in version 4.2.3, Matlab users have found that an easy way to get their data into Figure Composer is to generate a Matlab figure first, then import the FIG file directly in FC. However, a figure created this way is typically "rough around the edges", not suitable for publication. You may spend an hour or two refining a figure's appearance, and you might use data located in several different Matlab-generated source figures. If you have to later revise the data, you will not want to go through the laborious process of rebuilding the finished figure again. Instead, use the Extract/Inject raw data commands to inject the revised data from your updated source figures into the original publication-ready figure. If you have to inject many data sets from several different sources, you may prefer to use the File|Inject Data command, discussed earlier in this chapter.

Any property that represents or is related to the specific content, location, or dimensions of the node are generally NOT included in the style set. The Copy styling command is disabled if the currently selected node does not support style sets. The Paste styling command will be disabled if there is no style set to apply, or if applying that style set to the currently selected node(s) would not change it in any way.

Note that the Paste styling command works even if multiple objects are selected in the figure -- so you can make the same styling changes to multiple nodes in one go; and if you don't like the result, you can simply Undo it! 

Use case. Your figure contains six graphs of similar data, and you want to change the color, stroke width, and marker symbols used to render a trace in each of the six plots. Rather than editing each and every trace node separately, you make the necessary changes on one node. Then copy its styling, multi-select the other five traces, and apply the copied style set to all of those traces at once. The rendered appearance of the traces are updated without affecting the trace data.

Alignment operations are always defined with respect to the current anchor node in the selection. This node is distinguished from the others by a bright blue outline in both the Figure Navigator and the Figure Canvas. There are six alignment options:

• • Left : Objects are aligned along the left edge of the anchor node.

  • Right: Objects are aligned along the right edge of the anchor node.

  • Bottom: Objects are aligned along the bottom edge of the anchor node.

  • Top: Objects are aligned along the top edge of the anchor node.

  • Horizontal Center: Objects are centered horizontally along the horizontal midline of the anchor node

  • Vertical Center: Objects are centered vertically along the vertical midline of the anchor node.

The objects are typically aligned by updating the X- or Y-coordinate of their current location appropriately; the coordinate's unit of measure is preserved.  In the case of a label node, the label's horizontal or vertical text alignment may also be changed.

Like all other multi-node operations, the alignment commands can be undone and redone as a single, atomic operation.

This menu item raises a sub-menu listing all the types of FypML graphic objects that may be added to a figure. The toolbar includes a corresponding button for each type of object, and most have a keyboard shortcut. The "insert object" commands are organized into three groups, and there are submenus for the 2D and 3D groups:

• • Generic objects: Text label (Ctrl-Shift-L), Text box (Ctrl-Shift-E), Image (Ctrl-Shift-M), Shape (Ctrl-Shift-W), and Line Segment (Ctrl-Shift-N).

• 2D plots: Graph (Ctrl-Shift-G), , Trace (Ctrl-Shift-T), Function (Ctrl-Shift-F), Raster (Ctrl-Shift-R), Contour Plot (Ctrl-Shift-H), Calibration bar (Ctrl-Shift-C), Box Plot (no hot key), Bar Plot (Ctrl-Shift-B), Area Chart (Ctrl-Shift-A), Pie Chart (Ctrl-Shift-Y), and Scatter Plot (Ctrl-Shift-K)

• 3D plots: 3D Graph (Ctrl-Shift-D), 3D Scatter Plot, and Surface Plot.

Each of these "insert graphic" menu commands will create a new instance of the relevant FypML node (with default property values) and append it to the child list of the currently selected node. If that is not possible because the selected node does not allow children, Figure Composer will instead insert it as a sibling of the selected node, just before it in the parent's child list. The Figure Canvas and Figure Navigator are updated to show the newly inserted node, which is also selected so that you can immediately view and edit its definition in the Property Editor.

Each "insert graphic" command is enabled only if it corresponds to a node type that can be added as a child or sibling of the currently selected node. For example, the figure node cannot "parent" a trace node; thus, if the selection is on the root figure node, the Edit|Insert>2D>Trace command is disabled. If the new node is valid both as a child or as a sibling of the selected node, then Figure Composer will raise a dialog to ask you where it should be inserted. If there is no ambiguity (for example, a trace node can only appear as the child of a graph), then the dialog does not appear.

None of the "insert graphic" commands are enabled if multiple nodes are currently selected in the figure.