Skip to Content

The Proto Environment: Part 3: The Viewer

An in-depth look at the Viewer and its various elements

This article provides an introductory look at Proto. It is part of a three-part series, which also includes Part 1: Introducing Proto and Part 2: The Builder.

Introduction

This article, along with the other two parts in this series, are intended to provide a quick introduction to the Proto environment and its basic elements. This feature completes the series by documenting the Viewer window in greater detail.

The Viewer is the interactive, customizable interface of a custom module that displays its contained module’s controls. In this window you can interact with your custom module and display its underlying information in graphic and tabular displays. You can also print and copy images of the Viewer for use elsewhere.

Customizing the Viewer

You are able to fully customize the layout and appearance of a custom module’s Viewer. You can resize, rearrange, and hide each Viewer control as well as resize the entire Viewer window as needed. Resizing the Viewer is similar to resizing any other window: drag any of the window’s edges or corners to adjust that boundary. If the Viewer window is in full-screen mode, you must click the Maximize button to change it into a regular window before you can resize it. It is possible to resize the Viewer to an area smaller than the area that the controls take up. In this case, scroll bars appear enabling you to view only a partial section of the Viewer.

It is possible to specify whether or not a control appears in the Viewer or not. By default, all controls are visible, but you can set whether or not its visible by toggling the “Visible” check box in the General tab of the module’s Property Panel or by sending an appropriate message to the module’s “Set Control Visible” input connector. Furthermore, you can display controls in the Viewer, but prevent them from responding to user interaction by sending an appropriate message to the “Set Control Enabled” input connector. This is useful if you need a Text Box, for example, to display data but prevent that data from being edited by the user.

The control’s label can also be hidden in the Viewer. By default, labels are visible in the Viewer. The “Show label in Viewer” check box in the General tab of a module’s Property Panel determines whether or not the label is displayed.

Edit Mode allows you to resize each control and arrange them however you would like. While Edit Mode is on, select an individual control to manipulate by clicking an individual control or dragging a rectangular region in the Viewer that overlaps the control. You can select and manipulate multiple controls at the same time by either dragging a region containing multiple controls or by holding CTRL while clicking multiple Viewer controls.

To toggle Edit Mode:

  • Select Edit Controls from the Tools menu in the Viewer
  • Press CTRL+E.
  • Click the Edit Controls button in the upper right of the Viewer window.
  • Right-click on the background of the Viewer and select Edit Controls.

Aligning and Arranging Viewer Controls

There are several tools to aid in laying out Viewer controls while in Edit Mode. The location of Viewer controls can be constrained to locations on a fixed 8 pixel grid. The alignment commands allow you to layout the controls so that they are vertically or horizontally aligned. The arrange commands allows controls to be moved in front of or behind one another.

The Viewer positioning grid is a regularly spaced grid that constrains the possible locations of Viewer controls while in Edit Mode. It makes it easier to arrange and align Viewer controls. The grid can be turned on or off by selecting the Snap to Grid command in the Tools menu or by clicking the Alignment Grid button in the lower right of the Viewer window. When the Viewer is in Edit Mode and the grid is active, dots are drawn on the background of the Viewer to indicate the spacing that controls will be constrained to. By default the grid is on in new Viewer windows.

The align commands provide a way to align controls both vertically and horizontally if multiple controls are selected. To align controls, first enter Edit Mode. Then select more than one control. Then select an alignment from the Align submenu in the Tools menu. The methods for aligning the controls are:

  • Left Edges: the left edges of the controls are aligned
  • Horizontal Centers: the center of the controls are aligned horizontally
  • Right Edges: the right edges of the controls are aligned
  • Top Edges: the top edges of the controls are aligned
  • Vertical Centers: the centers of the controls are aligned vertically
  • Bottom Edges: the bottom edges of the controls are aligned

The arrange commands provide a way to arrange how controls overlap and whether they appear in front of or behind each other in the Viewer. To arrange controls, first enter Edit Mode. Then select at least one control. Then select one of the menu items from the Arrange submenu in the Tools menu. If Bring to Front is selected the control will be brought in front of all other controls. If Send to Back is selected the control will be sent behind all other controls.

Finding a Control’s Module in the Builder

While building a complicated custom module it can be difficult to keep track of which Viewer controls are associated with which module in the Builder. This feature allows easy navigation from a Viewer control to its associated Builder module. To find a control’s module right-click on a Viewer control and select Find in Builder from the menu. The Builder window will become active and the module associated with the Viewer control will be selected.

Interacting with Viewer Controls

Each control module contained in your custom module will display a control in the Viewer window. The basic modules each display a different type of control in the Viewer. Depending on which module it controls, how that module is connected to other modules, and how that module’s properties are configured, different Viewer controls can vary greatly in appearance and interface. For more information about a certain module and its control, please refer to the Module documentation.

Embedded Modules in the Viewer

When custom modules that contain Viewer controls are embedded in other custom modules by default their Viewer controls are still displayed in their parent module’s Viewer. There is an embedded Viewer area for each embedded custom module. By default these embedded modules are surrounded by a special border with the name of the custom module displayed at the top. It is possible to remove this border and have the embedded module blend in more cleanly with the rest of the Viewer. To do this right-click on the custom module and select Properties…. In the Viewer Presentation area of the Property Panel select “None.” Click Save and the embedded module takes on the new appearance. When the main Viewer window enters Edit Mode any embedded Viewers become movable and resizable. The controls contained inside the embedded Viewer are movable and resizable as well. When a custom module has its presentation set to “Pop up” its controls can be edited only if its pop up window is open when entering Edit Mode.

Capturing and Printing Images of the Viewer

Viewer Capture (VC) refers to the ability to capture regions of the Viewer as images to clipboard. There are two basic modes of VC exposed by the framework:

  • Whole Viewer Capture (WVC): capturing the entire visible area of the viewer. This should include just the “client” area of the Viewer. No menu bars, form border or scroll bars should be present in the clipboard image.
  • Viewer Element Capture (VEC): capturing the image of a single Proto Control. The copied area should be just that of the visible control. It should not include the label. There are not currently strong requirements as to what should happen if a control is partially obscured – the easiest behavior is acceptable.
  • These operations are exposed via the right-click menu(s) in the Viewer. The right-click menu for the Viewer’s background should have an additional item: Copy Whole Viewer Image. Selecting this item should immediately execute a WVC and place the resulting image in the clipboard. The right-click menu for all Proto Control should have an additional item: Copy Control Image. Selecting this item should immediately execute a VEC on the target of the right-click and place the resulting image in the clipboard.

The Status Bar

The status bar at the bottom of the Viewer window provides execution feedback. The status bar displays the current state of execution: whether of not Proto is “Ready” and “Executing.” “Ready” is the default state; “Executing” means that the custom module is processing data. This is especially useful for knowing when a custom module is performing computationally intensive calculations or when interacting with Excel. When an error occurs in the execution flow, an alert message is displayed in the status bar. Clicking on the error message in the status bar will display a ToolTip that provides more information on the error.

Menus

Located at the top of the Viewer, the menus allow you to perform common program tasks. This is a description of the menus in the Viewer. The shortcut keys for menu commands are listed in parentheses.

The File menu:

  • New (CTRL+N): Opens a new, empty custom module with its own Builder and Viewer windows.
  • Open… (CTRL+O): Displays the Open Custom Module window, which allows you to browse your repository and open a saved custom module.
  • Close (CTRL+W): Closes the active Builder window. The custom module will remain open if its Viewer window is still open.
  • Close Document (ALT+F4): Closes the custom module’s Builder and Viewer windows.
  • Save (CTRL+S): Saves the current state of the custom module. Opens the Save As window if the custom module is not currently contained in the repository.
  • Save As… (CTRL+SHIFT+S): Allows you to provide a name, description, and permissions for this custom module and have it stored in the current repository.
  • Publish New Version…: Saves a new version of this custom module while retaining the previously saved versions in the repository. For more details, see the Versioning section of the Managing Custom Modules article.
  • Manage Resources → Custom Modules…: Opens the Manage Custom Modules window, which allows you to save, version, open, import, export, and set permissions for custom modules. For more details, see the Managing Custom Modules feature.
  • Manage Resources → ProtoDBs…: Opens the Database Repository Manager window, which allows you to perform all ProtoDB management functionality. For more details, see the Managing ProtoDB article.
  • Export Module…: Allows you to save this custom module as a .proto file anywhere on your computer. For more details, see the Managing Custom Modules article.
  • Import Module…: Opens the Import Module window, which allows you to open any .proto file saved on your computer in a new Builder and Viewer window. For more details, see the Managing Custom Modules article.
  • Manage Repository…: Opens the Repository Manager window. For more details, see the Repository feature.
  • Print Preview Viewer…: Opens the Print Preview window allowing you to preview what would be output if you printed the current Viewer.
  • Print Viewer…: Opens the Print window so you can print the Viewer.
  • Exit: Exits Proto by closing all custom modules and Proto windows.

The View menu:

  • Viewer (CTRL+~): Switches to the Viewer window that corresponds to this Builder.

The Tools menu:

  • Edit Controls: Puts the Viewer in Edit Mode.
  • Options…: Opens the Options window which allows you to enter the web login and toggle the dialog displayed when Proto starts.

The Help menu:

  • Getting Started: Displays a short guide to the documentation in your default web browser.
  • Help Contents: Opens the documentation contents page in your default web browser.
  • Proto on the Web: Opens Proto’s home page on the Internet in your default web browser.
  • Get Updates: Opens your web browser to the page on the Proto website that displays the latest update to Proto.
  • About: Shows the About window, which contains information about which version of Proto you are running.