Difference between revisions of "Sidebar"

Revision as of 13:46, 7 December 2012

The sidebar (working title) is a new feature likely to be in the 4.0 release. It combines ideas and code from both the Symphony sidebar and the OpenOffice Impress task pane.

The UX part of the work is described on another page. This page focuses on the API design and implementation.

Help in whatever form (writing code, designing the UI, testing) is welcome.

Status

We are in the early planning stage.

I activated the older and unfinished sidebar support that was done when OpenOffice was developed by Oracle. There are devloper snapshots for Linux (requires glibc >= 2.15: Ubuntu 12.4 or later, Fedora 17 or later...), Mac and Windows. These exist for reference and analysis. There appear to be several bugs, do not use these developer snapshots for editing valuable documents.

Screenshots from the developer snapshots. In all three screenshots mouse is over the third button from the top in the sidebar, button above is selected. Click to enlarge.

Linux: Mac: Windows:

Detail views of regular toolbar buttons. Right "abc" button is selected, mouse is over left "abc" button.

Linux: Mac: Windows:

Examples of toolbars in other applications:

Linux (file explorer): Mac (Garageband): Windows (File Explorer):

For comparison here is a screenshot from Symphony (on Windows):

Resources

• UX
  • UX design exploration
  • Pane Header UI Design
• Symphony
  • Assessment of the migrating the Symphony sidebar.
  • Older proposal to use the Symphony sidebar.
• AOO
  • Overview of an existing but unfinished attempt of implementing tool panels.
  • Introduction to writing tool panels.
  • Description of the drawing framework, that is used by the Impress tool panel.

Glossary

Work in progress. Comments are welcome.

Schematic overview of sidebar components. Location of elements do not reflect UX design.

sidebar

Name of the feature and name of the control including all its components (icon bar, content panels).

Also known as task pane(l) or tool pane(l)

tab bar

Similar to a vertical tool bar. Clicking on buttons switches between sidebar decks.

deck

Contains one or more content panels. Only one deck is visible at any one time.

content panel

Displays information about the document and/or provides the means for document modification.

Each content panel focuses on one topic like font, table or shape properties.

There may be more than one content panel in a deck.

Examples are the task panels of the Impress task pane or the property views of the Symphony sidebar.

title bar

Displays the title for the current sidebar deck.

Can contain a closer button.

content panel title

Displays the title for one content panel. Optional when there is only one content panel.

configuration menu button

Opens a popup menu that allows switching between decks and also allows the activation and deactivation (tab is not shown) of decks.

Implemenation design

The sidebar consists of two major components:

• The buttons in the vertical tab bar on the right switch manually between sidebar decks.
• The content area contains a two-tier hierarchy of deck and content panels. There is exactly one deck visible at any one time. It contains one or more content panels. A content panel can be displayed expanded or collapsed.

The set of visible deck and content panels changes when a context change is broadcast. Context changes occur for example when in Writer the cursor is moved from text into a table or when in Impress text editing of a shape is activated.

Decks and context panels are specified via configuration and UNO interfaces and thus can be implemented not only in the AOO core code but also by extensions.

Context change notification

Context changes are broadcast via the new ui::ContextSwitchEventMultiplexer singleton (which is based on the equally new ui::EventMultiplexer service).

Context change broadcasts have to be manually inserted into application code.

Notifications about context changes are restricted to single views by using the XController as selector: an XController object is passed to ui::EventMultiplexeraddEventListener() and ui::EventMultiplexerbroadcastEvent() methods.

The sidebars (there is one per document windown) listen for context change notifications and rearrange the set of visible decks and panels according to the configuration entries for each deck and panel.

There will be a predefined standard set of contexts but extensions can provide decks and panels for new contexts and can also notify context changes for them.

Content panels

Deccks and content panels are specified via the configuration. The new Sidebar.xcs defines schemas for decks and content panels that contain:

• UI title
• Application and context names for which a deck or a content panel is to be visible.
• Simple layout information. Two different schemas will be supported
  1. Use all the available space (distributed equally when more than one panel reuests this)
  2. Vertical stack. The default for content panels migrated from Symphony. Requres content panels to support a new interface XVerticalStackLayoutElement with the method getHeightForWidth()

For the actual creation of panel objects (decks do not need per-object implementation) the existing ui::UIElementFactoryManager and the configuration entries in the <application>WindowState configuration files are used.

Sidebar

It is the responsibility of the sidebar to display the right set of content panels for the current combination of application (writer, calc, impress, draw, base) and context (eg text-editing, table-is-selected).

The visible set of deck and content panels changes on three occasions:

1. A context change is notified via the ContextSwitchEventMultiplexer
2. User clicks on one of the buttons in the sidebar tab bar.
3. Explicit requests to show a certain deck or panel (used by Impress to show the layout panel when the user opens the page context menu and clicks Slide->Slide Layout)

Outline of the implementation work

The sidebar implementation has to address several individual issues:

API for providing content panels

• Content panels are created by factories.
• Factories are registered at one factory manager.
• Factories can be provided by
  • Internal code that is part of the AOO SVN repository.
  • External extensions from the extension repository.

API for internal handling of the sidebar

• Activation of content panes
• Detection of visible/active content panels
• Receiver of context switch notifications
• Factory for registering content panels and associations between contexts and content panels.

API for aiding in implementing content panels

Optional but important for sidebar adoption by developers.

• Simple layout manager
• Notification of important events

like switching to/from high contrast mode

• Skeletons for content panels and factory registration

Implementation of context switch handling

• Receiver of context switch notifications as controller that updates the set of active content panels accodring to the new context.
• Factory and container for providers of content panels
• Extend Writer, Calc, Impress with context switch notifications.
  • This may follow toolbar switches.
  • Maybe toolbar switching can generate the notifications?

Framework for implementing content panels

• Base/helper classes for content panels, factories, registration, layouting.

Content panels

• Reuse code from AOO Impress and Symphony

Implementation of the actual side bar

• • Icon bar as special case of tab bar.
  • Display of one or more content groups
  • Display of one or more content panels inside each content group.
  • Display of scroll bars when sidebar becomes too small for displaying all active content panels.

Existing implementation

Not all the API design and implementation work has to be started from scratch. There several parts that can be used/reused/adapted.

In main/sd/

The drawing framework is used for the Impress taskpane, all Impress views and the slide show. A tree of URLs (called a configuration) defines the different layers of containers (windows) and views (taskpane panels). SD views only modify a configuration, update and synchronization of the associated view shells is left to the ConfigurationController.

Contextual changes of tool bars are handled in SD in a single place by the ToolBarManager. It receives notifications about context changes by registering as listener at the EventMultiplexer.

Example: When an Impress shape enters text edit mode then sd::View sends an event to the EventMultiplexer. That forwards the event to the ToolBarManager. The ToolBarManager checks its set of rules, finds the one that activates the text edit tool bar and replaces the current context bar with the text edit bar.

In main/svtools/ and main/sfx2/

The unfinished implementation of an office wide toolpane with Symphony like functionality can be found in svtools/source/toolpanel/ and sfx2/source/dialog/taskpane/. See Framework/Article/Tool Panels Internals for details.

Here is a schematic of the UI: .

Existing API (main/offapi/)

XUIElement and XToolPanel from com::sun::star::ui provide an API abstraction of the toolpanel.

It is already possible to provide new tool panels from an extension.

In the symphony branch

The sidebar is implemented in sfx2/source/propertypanel. Base functionality for sidebar and content panes can be found in svx/source/propertypanel.

Find application specific content panels in sw/source/ui/propertypanel, sc/source/ui/propertypanel, sd/source/ui/propertypanel. In these directories the files propertydlg.cxx defines the set of panels that are to be displayed. These lists are hardcoded and can not be modified by extensions.

Painting of control backgrounds is also hardcoded. Look for instance at svx/source/propertypanel/paragraphpropertypage.cxx and search for calls to DrawGradient(). Colors for the background gradients are defined in every file that paints button backgrounds.