Space: Apache OpenOffice Community
(https://cwiki.apache.org/confluence/display/OOOUSERS)
Page: Sidebar Introduction
(https://cwiki.apache.org/confluence/display/OOOUSERS/Sidebar+Introduction)
Change Comment:
---------------------------------------------------------------------
Added link to UX guidance on sidebar design
Edited by Kevin Grignon:
---------------------------------------------------------------------
*{+}Sidebar overview{+}*
A sidebar is a replace or an alternative to toolbar. Normally it will docked in
the right side of whole window. It can also be floated to other places by
dragging the dock window title bar. A sidebar contains two parts: panel
dock(right narrow window like a vertical table bar) and dock window(left side).
Panel dock contains some buttons which is used to show/hide left related dock
window. A button is expressed with a image which indicates the function of its
related dock window. A dock window can be design for property, style,
navigator, clip arts and so on. It contains a title bar and a panel. A panel
can contains several sections such as text section and paragraph section. A
section is divides two parts: section title bar and section page.
See Symphony Contribution UX Analysis for a user experience-oriented assessment
of issues and opportunities with the dockable task pane.
[http://wiki.openoffice.org/wiki/AOO_Symphony_UX_Migration/Merge_Analysis_-_Task_Pane]
!sidebar.JPG|border=1!
*{+}Sidebar code view{+}*
Sidebar implementation is mainly in sfx module. Related files or concept is as
follows. The object down will be created by the object up.
!General.jpg|border=1!
For above picture, below concept are referred to:
|| Concept || Roles ||
| Dispatcher | {color:#000000}Internally maintains a stack of objects, each
representing a context. Examples for these contexts are “document”, “view”,
“text”, “table”, “cell” etc{color}\\ |
| Binding \\ | Associate for dispatcher. To be a connector between dispatcher
and context state. |
| Context | A specific situation, such as the current selection or cursor
position in a document, has a context \\ |
| View frame(shell) \\ | View frame extended from shell. Context is represented
by a stack of shell object |
| Interface \\ | Each interface has a static slot array |
| Slot \\ | Slot represents a command \\
2) contains function pointers to \\
execute the command or get \\
status information about it \\
3) has a unique slotID \\
Represents a command. Contains functions pointers to execute the command or get
status info about it. Has a unique slotID |
| Work window \\ | Dispatch use it to created sidebar child window. |
| Child window \\ | Child window is not a real window. But it relates with a
real window which can be a docking window. It is a data structure for framework
to operate real window in a common way. |
| Others \\ | Dock window, panel and section are easy to be understood from the
overview picture. |
For more details, refer to
here: [http://wiki.services.openoffice.org/wiki/Framework/Article/Implementation_of_the_Dispatch_API_In_SFX2]
*{+}Sidebar creation process{+}*
This section will focus on sidebar creation process. It will take property dock
window in spreadsheet as an example. Most of classes will be referred to.
Besides, some key content out of creation process will be listed.
1. Child window and factory registration
When module(sc) is initialized, it will register all interfaces containing
child window interface in corresponding SfxInterface through ScTabeViewShell.
Child window factory will also be registered in application through
ScPropertyDockWinWrapper(extends from basic SfxChildWindow). Later the factory
will be used to created property child window.
!window_registration.jpg|border=1!
2. Panel dock creation
The panel dock will always lies in the rightest of window and it cannot be
moved. It will be used to show/hide dock window. So it will be created in the
first. Here panel dock class is named SfxTabbarWin. From the code view picture,
we can understand the process clearly. SfxFrame is a shell. Shell create panel
dock window through SfxWorkWindow.
!panel_dock_creation.jpg|border=1!
3. Dock(Child) window creation
(1) Define SID_PROPERTY_SIDEBAR_DLG
{quote}
\#define SID_PROPERTY_SIDEBAR_DLG(SID_SVX_START + 1100)
{quote}
(2) Slot definition in sdi file
{quote}
SID_PROPERTY_SIDEBAR_DLG
\[
ExecMethod = ChildWindowExecute ;
StateMethod = ChildWindowState ;
\]
{quote}
(3) state method definition and implementation(also part of slot)
{quote}
SfxBoolItem PropertyPanel SID_PROPERTY_SIDEBAR_DLG
\[
/\* flags: \*/
AutoUpdate = TRUE,
Cachable = Cachable,
FastCall = TRUE,
HasCoreId = FALSE,
HasDialog = FALSE,
ReadOnlyDoc = FALSE,
Toggle = FALSE,
Container = FALSE,
RecordAbsolute = FALSE,
RecordPerSet;
Synchron;
Readonly = FALSE,
/\* config: \*/
AccelConfig = TRUE,
MenuConfig = TRUE,
StatusBarConfig = FALSE,
ToolBoxConfig = TRUE,
GroupId = GID_FORMAT;
\]
{quote}
Its implementation is in the common shell “SfxViewFrame: public SfxShell”
{quote}
void
ChildWindowExecute(SfxRequest&);
{quote}
!docking_window_creation_1.jpg|border=1!
!docking_window_creation_2.jpg|border=1!
4. Property panel creation
Responsibility of PropertyPanel
* manage the life cycle of section control. AddSection(), RemoveSection(),
ClearSections()
* layout each section(set each section's position and size).
* manage when to show or hide scrollbar, set size of the scroll window.
Rearrange(), SetupScrollBars(), SetupVerticalScrollBar(),
SetupHorizontalScrollBar(), scroll scrollBar, ScrollBarHandler()
* context switch, delegate the function to ContextSwitchHelper class
* maintain section state(expand/collapse) during context switch, delegate the
function to ContextSwitchHelper class
Responsibility of ContextSwitchHelper
* store the relationship of context and sections. map<ContextID,
vector<SectionID>> macontext2sections, InitCtxt2SectionInfos().
* store section infos. vector<PanelSectionInfo> maSectionInfos,
InitSectionInfos().
* context switch. contextSwitch(ContextID)
* map<ContextID, SectioIDWithState> maDefaultStates, maContextStates;
* GetSectionState(), SetCurrentSectionState(), GetSectionDefaultState()
Key points
(1) Define SID_SVX_PROPERTY_CONTEXT
{quote}
\#define SID_SVX_PROPERTY_CONTEXT(SID_SVX_START + 1101)
{quote}
(2) Use SfxControllerItem to create the relationship between
SID_SVX_PROPERTY_CONTEXT and SfxBindings and SfxDispatcher. This happens when
property panel is creating
{quote}
mpCtxItem(new SfxPropertyContextItem(SID_SVX_PROPERTY_CONTEXT,*mpBindings,this))
{quote}
!docking_window_creation_3.jpg|border=1!
5. Section creation with context sensitive
(1) Slot definition in sdi file
{quote}
SfxUInt16Item PropertyContextId SID_SVX_PROPERTY_CONTEXT
\[
/\* flags: \*/
AutoUpdate = TRUE,
Cachable = Cachable,
FastCall = TRUE,
HasCoreId = FALSE,
HasDialog = FALSE,
ReadOnlyDoc = FALSE,
Toggle = FALSE,
Container = FALSE,
RecordAbsolute = FALSE,
RecordPerSet;
Synchron;
Readonly = FALSE,
/\* config: \*/
AccelConfig = TRUE,
MenuConfig = TRUE,
StatusBarConfig = FALSE,
ToolBoxConfig = TRUE,
GroupId = GID_FORMAT;
\]
{quote}
(2) state method definition and implementation(also part of slot)
{quote}
SID_SVX_PROPERTY_CONTEXT
\[
StateMethod = GetPropertyContextId ;
\]//please pay attention that its interface is name Window.
{quote}
Its implementation is in the common shell “SfxViewFrame: public SfxShell”
{quote}
SAL_DLLPRIVATE void GetPropertyContextId( SfxItemSet &rSet );
{quote}
(3) If context is changed, dispatcher will call binding's update_Impl. In it,
SfxStateCache(pCache) will be got from bindings. And this state will be set.
Then controller's stateChanged will be called. And property panel will switch
context according to context id. Related sections will be added in panel. Below
the first picture follows the first picture in "Dock(Child) window creation"
part.
!docking_window_creation_4.jpg|border=1!
!docking_window_creation_5.jpg|border=1!
Change your notification preferences:
https://cwiki.apache.org/confluence/users/viewnotifications.action
