|
|
| Line 8: |
Line 8: |
| | | | |
| | | | |
| − | ==Status==
| |
| − | The main implementation work is finished. We are now fixing bugs and doing visual fine tuning.
| |
| − |
| |
| − | Here is how it looks:
| |
| − | [[File:sidebar-2013-04-15.png|400px]]
| |
| − |
| |
| − | ==Resources==
| |
| − |
| |
| − | * UX
| |
| − | **[[AOO_UX_Design_Exploration_-_Task_Pane_Content_-_Information_Design|UX design exploration]]
| |
| − | **[[AOO_UX_Design_Exploration_-_Docked_Task_Pane_Container_-_Pane_Header_User_Interface_Design|Pane Header UI Design]]
| |
| − | **[[AOO_UX_Design_Exploration_-_Task_Pane_Content_Panel_-_User_Interface_Design_Proposals|UX Design propoals]]
| |
| − | * Symphony
| |
| − | ** Assessment of the [[AOO_Symphony_UX_Migration/Merge_Analysis_-_Task_Pane|migrating the Symphony sidebar]].
| |
| − | ** Older proposal to use the [[Sidebar_Proposal_by_IBM|Symphony sidebar]].
| |
| − | * AOO
| |
| − | ** Overview of an existing but unfinished attempt of implementing [[Framework/Article/Tool_Panels_Internals|tool panels]].
| |
| − | ** Introduction to [[Framework/Article/Tool Panels|writing tool panels]].
| |
| − | ** Description of the [[Drawing framework|drawing framework]], that is used by the Impress tool panel.
| |
| − |
| |
| − | ==Developer Builds==
| |
| − | The sidebar branch has been integrated into trunk and is therefore available in all regular builds.
| |
| − |
| |
| − | Grab trunk builds off the build bots (Links?)
| |
| − |
| |
| − | If you find any bugs in the sidebar or caused by the sidebar then please write a BugZilla issue for each and
| |
| − | * Prefix the title with "sidebar:"
| |
| − | * Mark them as blocker of [https://issues.apache.org/ooo/show_bug.cgi?id=121420 issue 121420].
| |
| − | * Assign it to me (awf dot aoo at googlemail dot com)
| |
| − |
| |
| − | Known bugs:
| |
| − | * Crashes caused by dispatching uno commands [https://issues.apache.org/ooo/show_bug.cgi?id=122028 122028] and [https://issues.apache.org/ooo/show_bug.cgi?id=122030 122030] (with patches)
| |
| − | * Disabling of uno commands does not work [https://issues.apache.org/ooo/show_bug.cgi?id=121960 121960]
| |
| − | * Uno commands not labeled and not well named [https://issues.apache.org/ooo/show_bug.cgi?id=122025 122025] and [https://issues.apache.org/ooo/show_bug.cgi?id=122026 122026]
| |
| − |
| |
| − | Requested improvements/changes:
| |
| − | * Make the visible controls in panels customizable similar to toolbars [https://issues.apache.org/ooo/show_bug.cgi?id=121940 121940]
| |
| − | * Change request for the association of contexts and panels: show area and line panel for OLE objects, show the area panel for images [https://issues.apache.org/ooo/show_bug.cgi?id=121936 121936] and [https://issues.apache.org/ooo/show_bug.cgi?id=121937 121937].
| |
| − | * Show legacy sidebar extensions in the old, not in the new sidebar [https://issues.apache.org/ooo/show_bug.cgi?id=122057 122057].
| |
| | | | |
| | ==Glossary== | | ==Glossary== |
| Line 96: |
Line 57: |
| | ;Paragraph: TBD. | | ;Paragraph: TBD. |
| | ;Wrap: TBD. | | ;Wrap: TBD. |
| − |
| |
| − |
| |
| − | ===Contexts===
| |
| − |
| |
| − | The following table shows the association between panels and dialogs for all supported contexts. It also lists whether panels are initially displayed expanded or collapsed and the uno command to use to open a more detailed dialog. Applications are abreviated:
| |
| − | * SC - Calc
| |
| − | * SD - Draw and Impress
| |
| − | * SW - Writer
| |
| − |
| |
| − | {| class="prettytable sortable"
| |
| − | !Panel
| |
| − | !Application
| |
| − | !Context
| |
| − | !Initially visible
| |
| − | !Detail dialog command
| |
| − | |-
| |
| − | |Alignment ||SC|| Auditing ||yes|| .uno:Hyphenate
| |
| − | |-
| |
| − | |Alignment ||SC|| Cell ||yes|| .uno:Hyphenate
| |
| − | |-
| |
| − | |Alignment ||SC|| EditCell ||yes|| .uno:Hyphenate
| |
| − | |-
| |
| − | |Alignment ||SC|| Pivot ||yes|| .uno:Hyphenate
| |
| − | |-
| |
| − | |Area ||SC|| Draw ||yes|| .uno:FormatArea
| |
| − | |-
| |
| − | |Area ||SD|| 3DObject ||yes|| .uno:FormatArea
| |
| − | |-
| |
| − | |Area ||SD|| Draw ||yes|| .uno:FormatArea
| |
| − | |-
| |
| − | |Area ||SD|| TextObject ||no || .uno:FormatArea
| |
| − | |-
| |
| − | |Area ||SW|| Draw ||yes|| .uno:FormatArea
| |
| − | |-
| |
| − | |Cell Appearance ||SC|| Auditing ||yes|| .uno:FormatCellDialog
| |
| − | |-
| |
| − | |Cell Appearance ||SC|| Cell ||yes|| .uno:FormatCellDialog
| |
| − | |-
| |
| − | |Cell Appearance ||SC|| Pivot ||yes|| .uno:FormatCellDialog
| |
| − | |-
| |
| − | |Graphic ||SC|| Graphic ||yes|| -none-
| |
| − | |-
| |
| − | |Graphic ||SD|| Graphic ||yes|| -none-
| |
| − | |-
| |
| − | |Graphic ||SW|| Graphic ||yes|| -none-
| |
| − | |-
| |
| − | |Line ||SC|| Draw ||yes|| .uno:FormatLine
| |
| − | |-
| |
| − | |Line ||SC|| Graphic ||yes|| .uno:FormatLine
| |
| − | |-
| |
| − | |Line ||SD|| 3DObject ||yes|| .uno:FormatLine
| |
| − | |-
| |
| − | |Line ||SD|| Draw ||yes|| .uno:FormatLine
| |
| − | |-
| |
| − | |Line ||SD|| Graphic ||yes|| .uno:FormatLine
| |
| − | |-
| |
| − | |Line ||SD|| TextObject ||no || .uno:FormatLine
| |
| − | |-
| |
| − | |Line ||SW|| Draw ||yes|| .uno:FormatLine
| |
| − | |-
| |
| − | |Number Format ||SC|| Auditing ||no || .uno:FormatCellDialog
| |
| − | |-
| |
| − | |Number Format ||SC|| Cell ||no || .uno:FormatCellDialog
| |
| − | |-
| |
| − | |Number Format ||SC|| Pivot ||no || .uno:FormatCellDialog
| |
| − | |-
| |
| − | |Wrap ||SW|| Graphic ||yes|| .uno:ObjectWrapDialog
| |
| − | |-
| |
| − | |Wrap ||SW|| OLE ||yes|| .uno:ObjectWrapDialog
| |
| − | |-
| |
| − | |Wrap ||SW|| Frame ||yes|| .uno:ObjectWrapDialog
| |
| − | |-
| |
| − | |Layouts ||SD|| DrawPage ||yes|| -none-
| |
| − | |-
| |
| − | |Layouts ||SD|| HandoutPage ||yes|| -none-
| |
| − | |-
| |
| − | |Layouts ||SD|| NotesPage ||yes|| -none-
| |
| − | |-
| |
| − | |Layouts ||SD|| SlidesorterPage ||yes|| -none-
| |
| − | |-
| |
| − | |Page ||SW|| Table ||no || .uno:PageDialog
| |
| − | |-
| |
| − | |Page ||SW|| Text ||no || .uno:PageDialog
| |
| − | |-
| |
| − | |Paragraph ||SC|| DrawText ||yes|| .uno:ParagraphDialog
| |
| − | |-
| |
| − | |Paragraph ||SD|| 3DObject ||yes|| .uno:ParagraphDialog
| |
| − | |-
| |
| − | |Paragraph ||SD|| Draw ||no || .uno:ParagraphDialog
| |
| − | |-
| |
| − | |Paragraph ||SD|| DrawText ||yes|| .uno:ParagraphDialog
| |
| − | |-
| |
| − | |Paragraph ||SD|| Graphic ||no || .uno:ParagraphDialog
| |
| − | |-
| |
| − | |Paragraph ||SD|| Table ||yes|| .uno:ParagraphDialog
| |
| − | |-
| |
| − | |Paragraph ||SD|| TextObject ||yes|| .uno:ParagraphDialog
| |
| − | |-
| |
| − | |Paragraph ||SW|| Annotation ||yes|| .uno:ParagraphDialog
| |
| − | |-
| |
| − | |Paragraph ||SW|| DrawText ||yes|| .uno:ParagraphDialog
| |
| − | |-
| |
| − | |Paragraph ||SW|| Table ||yes|| .uno:ParagraphDialog
| |
| − | |-
| |
| − | |Paragraph ||SW|| Text ||yes|| .uno:ParagraphDialog
| |
| − | |-
| |
| − | |Position and Size ||SC|| Draw ||no || .uno:TransformDialog
| |
| − | |-
| |
| − | |Position and Size ||SC|| Form ||yes|| .uno:TransformDialog
| |
| − | |-
| |
| − | |Position and Size ||SC|| Graphic ||no || .uno:TransformDialog
| |
| − | |-
| |
| − | |Position and Size ||SC|| Media ||yes|| .uno:TransformDialog
| |
| − | |-
| |
| − | |Position and Size ||SC|| MultiObject ||yes|| .uno:TransformDialog
| |
| − | |-
| |
| − | |Position and Size ||SC|| OLE ||yes|| .uno:TransformDialog
| |
| − | |-
| |
| − | |Position and Size ||SD|| 3DObject ||yes|| .uno:TransformDialog
| |
| − | |-
| |
| − | |Position and Size ||SD|| Draw ||no || .uno:TransformDialog
| |
| − | |-
| |
| − | |Position and Size ||SD|| Form ||yes|| .uno:TransformDialog
| |
| − | |-
| |
| − | |Position and Size ||SD|| Graphic ||no || .uno:TransformDialog
| |
| − | |-
| |
| − | |Position and Size ||SD|| Media ||yes|| .uno:TransformDialog
| |
| − | |-
| |
| − | |Position and Size ||SD|| MultiObject ||yes|| .uno:TransformDialog
| |
| − | |-
| |
| − | |Position and Size ||SD|| OLE ||yes|| .uno:TransformDialog
| |
| − | |-
| |
| − | |Position and Size ||SD|| TextObject ||no || .uno:TransformDialog
| |
| − | |-
| |
| − | |Position and Size ||SW|| Draw ||no || .uno:TransformDialog
| |
| − | |-
| |
| − | |Position and Size ||SW|| Form ||yes|| .uno:TransformDialog
| |
| − | |-
| |
| − | |Position and Size ||SW|| Graphic ||yes|| .uno:GraphicDialog
| |
| − | |-
| |
| − | |Position and Size ||SW|| Media ||yes|| .uno:TransformDialog
| |
| − | |-
| |
| − | |Position and Size ||SW|| OLE ||yes|| .uno:FrameDialog
| |
| − | |-
| |
| − | |Table Design ||SD|| Table ||yes|| -none-
| |
| − | |-
| |
| − | |Text ||SC|| Auditing ||yes|| .uno:CellTextDlg
| |
| − | |-
| |
| − | |Text ||SC|| Cell ||yes|| .uno:CellTextDlg
| |
| − | |-
| |
| − | |Text ||SC|| DrawText ||yes|| .uno:FontDialog
| |
| − | |-
| |
| − | |Text ||SC|| EditCell ||yes|| .uno:FontDialog
| |
| − | |-
| |
| − | |Text ||SC|| Pivot ||yes|| .uno:CellTextDlg
| |
| − | |-
| |
| − | |Text ||SD|| 3DObject ||yes|| .uno:FontDialog
| |
| − | |-
| |
| − | |Text ||SD|| Draw ||no || .uno:FontDialog
| |
| − | |-
| |
| − | |Text ||SD|| DrawText ||yes|| .uno:FontDialog
| |
| − | |-
| |
| − | |Text ||SD|| Graphic ||no || .uno:FontDialog
| |
| − | |-
| |
| − | |Text ||SD|| OutlineTExt ||yes|| .uno:FontDialog
| |
| − | |-
| |
| − | |Text ||SD|| Table ||yes|| .uno:FontDialog
| |
| − | |-
| |
| − | |Text ||SD|| Textobj ||yes|| .uno:FontDialog
| |
| − | |-
| |
| − | |Text ||SW|| Annotation ||yes|| .uno:FontDialog
| |
| − | |-
| |
| − | |Text ||SW|| DrawText ||yes|| .uno:FontDialog
| |
| − | |-
| |
| − | |Text ||SW|| Table ||yes|| .uno:FontDialog
| |
| − | |-
| |
| − | |Text ||SW|| Text ||yes|| .uno:FontDialog
| |
| − | |-
| |
| − | |}
| |
| − |
| |
| − | ==Implemenation design==
| |
| − |
| |
| − | The UI of 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 one deck visible at any one time. It contains one or more content panels. A content panel can be displayed expanded or collapsed.
| |
| − |
| |
| − | The visible deck and content panels depend on the current context. Each context change may result in replacing one set of visible panels with another or changing the whole deck. A context consists of two strings:
| |
| − | *The id of the current application (like <code>com.sun.star.text.TextDocument</code> for Writer).
| |
| − | *The name of the actual context (like <code>Text</code> for text editing, <code>Table</code> for editing table content, or <code>default</code> for the default context)
| |
| − |
| |
| − | ===Context===
| |
| − | What makes up a context depends on the application. For example <code>Text</code> is the default context for Writer but in Impress you have to select a text object to enter that context.
| |
| − |
| |
| − | ====Context change notification====
| |
| − | Context changes are broadcast office wide via the <code>com::sun::star::ui::ContextChangeEventMultiplexer</code> singleton service and <code>com::sun::star::ui::XContextChangeEventMultiplexer</code> interface. In order to restrict the communication to one application window there exists the concept of the event focus. When you register as context change event listener or broadcast a change notification then you pass a event focus object. Only when listener and broadcaster use the same event focus object then the notification will pass from broadcaster to listener. Typically the event focus object is the controller of the application.
| |
| − |
| |
| − | To make life easier for developers there exists the <code>svx::sidebar::ContextChangeEventMultiplexer</code> frontend that
| |
| − | - figures out the application name and event focus from either a given <code>frame::XController</code> or <code>SfxViewShell</code> object.
| |
| − | - accepts only enum values from <code>sfx2::sidebar::EnumContext::Context</code> to prevent typos in context names to not correctly deliver context change events.
| |
| − |
| |
| − | On the receiving side of context change events there is the <code>sfx2::sidebar::SidebarPanelBase</code> base class for panel implementations. Let your panel implement the <code>sfx2::sidebar::IContextChangeReceiver</code> interface, use SidebarPanelBase (which probably needs a better name) as glue code between the sidebar framework and your panel and context change events will be delivered to you via the <code>IContextChangeReceiver::HandleContextChange()</code> method. Not all panels need to be informed about context changes. For many it is enough that they are activated for some contexts and deactivated for others.
| |
| − |
| |
| − | ====Forced context changes====
| |
| − | By default the property deck is displayed. The user can switch between decks by clicking on buttons in the tab bar. This will result in the forced notification of a context change.
| |
| − |
| |
| − | ===Defining the set of decks and panels===
| |
| − | Apart from the actual implementation the sidebar framework needs to know which decks and panels exists, which panels are to be displayed in each deck and for what configuration to display each deck and panel.
| |
| − |
| |
| − | The configuration files <code>Sidebar.xcs</code> (schema) and <code>Sidebar.xcu</code> (data) can be found in the <code>main/officecfg</code> module. They describe a list of decks and a list of panels.
| |
| − |
| |
| − | ====Decks====
| |
| − | Each deck has
| |
| − | *a unique id ("Id") which is referenced by panels that are to be displayed in the deck
| |
| − | *a localized title ("Title") for display in the deck title bar
| |
| − | *two URLs for the icon in the tab bar, one ("IconURL") is the default icon, the other ("HighContrastIconURL") is used when high contrast mode is active
| |
| − | *an integer number ("OrderIndex") that describes the order in which deck icons are displayed in the tab bar; higher values result in locations farther down.
| |
| − | *a string list of context descriptions ("ContextList") that specify for which contexts to display the deck; see more details about this in one of the next sections.
| |
| − |
| |
| − | ====Panels====
| |
| − |
| |
| − | Each panel has
| |
| − | *a unique id ("DeckId") which references a deck by its "Id" field; the panel will only be displayed in the referenced deck
| |
| − | *a localized title ("Title") for display in the deck title bar
| |
| − | *a flag ("TitleBarIsOptional") that indicates whether the title bar can be omitted when the panel is the only one in the deck
| |
| − | *a command name ("DefaultMenuCommand") for opening a dialog with more detailed options (eg. ".uno:FormatArea"); when no command is given then no menu icon will be displayed in the panel title bar
| |
| − | *an integer number ("OrderIndex") that describes the order in which panels are placed in their deck; higher values result in locations farther down.
| |
| − | *a string list of context descriptions ("ContextList") that specify for which contexts to display the deck. See more details about this in the the next section.
| |
| − | *a URL for specifying the implementation ("ImplementationURL") like <code>private:resource/toolpanel/SvxPanelFactory/AreaPropertyPanel</code>.
| |
| − |
| |
| − | ====Context Specification====
| |
| − | The "ContextList" properties of both decks and panels have basically a table form that is evaluated after each context change. If one of its rows matches the new context then deck or panel is displayed.
| |
| − |
| |
| − | Rows are really separated by semicolons (or whatever you specify in the opening <code>value</code> tag). Formatting them into rows just makes reading their content easier. Each row contains three or four values which are separated by commas. Leading and trailing spaces are ignored.
| |
| − |
| |
| − | Columns are:
| |
| − | ;Application name:
| |
| − | This can be the full application name as returned by <code>frame.ModuleManager</code> but to increase readability shorter names can also be used. There is a special name, <code>DrawImpress</code> for the common case that decks and panels are handled exactly the same in Draw and Impress. Similarily <code>WriterAndWeb</code> covers the applications Writer and Writer/Web.
| |
| − | Recognized values are:
| |
| − | com.sun.star.text.TextDocument
| |
| − | com.sun.star.text.WebDocument
| |
| − | com.sun.star.sheet.SpreadsheetDocument
| |
| − | com.sun.star.presentation.PresentationDocument
| |
| − | com.sun.star.drawing.DrawingDocument
| |
| − |
| |
| − | Writer
| |
| − | WriterWeb
| |
| − | Calc
| |
| − | Impress
| |
| − | Draw
| |
| − |
| |
| − | DrawImpress
| |
| − | WriterAndWeb
| |
| − | any
| |
| − | none
| |
| − | Most of these are self explanatory. <code>DrawImpress</code> and <code>WriterAndWeb</code> have been explained above. <code>any</code> matches any application while <code>none</code> matches no application. Use <code>none</code> to disable deck or panel temporarily during development.
| |
| − | ;Context name:
| |
| − | Recognized values are <code>3DObject</code>, <code>Annotation</code>, <code>Auditing</code>, <code>Cell</code>, <code>Chart</code>, <code>Draw</code>, <code>DrawPage</code>, <code>DrawText</code>, <code>EditCell</code>, <code>Form</code>, <code>Frame</code>, <code>Graphic</code>, <code>HandoutPage</code>, <code>MasterPage</code>, <code>Media</code>, <code>Multiobj</code>, <code>OLE</code>, <code>OutlineText</code>, <code>Pivot</code>, <code>SlidesorterPage</code>, <code>Table</code>, <code>Text</code>, <code>TextObject</code>.
| |
| − | It is, however, possible to invent your own context names.
| |
| − | The special value <code>any</code> matches any context name.
| |
| − | ;Initial state:
| |
| − | Can be either <code>visible</code> or <code>hidden</code>.
| |
| − | For decks this state decides whether the deck is initially enabled or disabled. You can change this state at runtime via the top button in the sidebar tab bar.
| |
| − | For panels this state controls whether the panel is initially expanded or collapsed. Click on the panel title bar to toggle this state.
| |
| − | ;Menu command override:
| |
| − | This optional value is only used for panels. It overrides the "DefaultMenuCommand" for the panel.
| |
| − |
| |
| − | Here is an example for the "Area" property panel:
| |
| − | <prop oor:name="ContextList">
| |
| − | <value oor:separator=";">
| |
| − | Calc, Draw, visible ;
| |
| − | DrawImpress, 3DObject, visible ;
| |
| − | DrawImpress, Draw, visible ;
| |
| − | DrawImpress, TextObject, hidden ;
| |
| − | Writer, Draw, visible ;
| |
| − | </value>
| |
| − | </prop>
| |
| − | The panel will be displayed for the "Draw" context for all applications. For Draw and Impress it will also be shown for contexts "3DObject" and "TextObject". The panel will be initially expanded except for the "TextObject" context for Draw and Impress. For this context it will be initially collapsed.
| |
| − |
| |
| − | ===Legacy addons===
| |
| − | Legacy addons are find in the application specific WindowState configuration files and instaniated via the existing ui::UIElementFactoryManager infrastructure is used.
| |
| − | 5.3 Sidebar
| |
| − |
| |
| − | ==Implementation and Migration==
| |
| − |
| |
| − | Bugzilla issue [https://issues.apache.org/ooo/show_bug.cgi?id=121420 121420] is the toplevel issue for the implementation of the sidebar.
| |
| − |
| |
| − | The implementation is finished. We are now fixing bugs and fine tune the UI.
| |
| − |
| |
| − | Extensions for the old sidebar are still supported. See [[Framework/Article/Tool_Panels|here]] for how this is done.
| |
| − |
| |
| − |
| |
| − | ==How to help / QA==
| |
| − |
| |
| − | The implementation and migration of a feature of this size provides a lot of opportunities for introducing new bugs or break existing functionality. Please help us find them.
| |
| − |
| |
| − | Snapshot builds are available for testing. Please see [[Sidebar#Developer_Builds|above]] for details.
| |
| − |
| |
| − | There are some simple documents for Writer, Calc and Impress then show you how switch to all the contexts and which panels should be visible then:
| |
| − | *Writer: [[File:Contexts-Writer.odt]]
| |
| − | *Calc: [http://people.apache.org/~af/sidebar/qa/Contexts-Calc.ods Contexts-Calc.ods]
| |
| − | *Impress: [http://people.apache.org/~af/sidebar/qa/Contexts-Impress.odp Contexts-Impress.odp]
| |
| − | These documents are not intended as test documents but as initial help for writing such documents.
| |
| − |
| |
| − | [[Category:Quality Assurance]]
| |
The sidebar is a new feature in the 4.0 release. It combines ideas and code from both the Symphony sidebar and the OpenOffice Impress task pane.
Help in every form is welcome. After reading the general introductory stuff:
Work in progress. Comments are welcome.
At any one time there is one and only one deck visible. It contains one or more panels. There are rare occasions where there is no panel for a given context, but in this case a replacement panel is displayed with a message to the effect "intentionally left blank".
The set of decks available via the tab bar and panels inside a deck depend on the current context. Contexts are defined by different features or states. This can be the selection of shapes, text editing on/off, switching between views (in Impress).
