Mailing-List: contact ooo-commits-help@incubator.apache.org; run by ezmlm
Precedence: bulk
Reply-To: ooo-dev@incubator.apache.org
Date: Thu, 27 Sep 2012 23:11:00 -0400 (EDT)
From: confluence@apache.org
To: ooo-commits@incubator.apache.org
Message-ID: <16908304.1513.1348801860046.JavaMail.confluence@thor>
Subject: [CONF] Apache OpenOffice Community > Sidebar Introduction
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: quoted-printable
Auto-Submitted: auto-generated

Space: Apache OpenOffice Community (https://cwiki.apache.org/confluence/dis=
play/OOOUSERS)
Page: Sidebar Introduction (https://cwiki.apache.org/confluence/display/OOO=
USERS/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 docke=
d 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 s=
ide). Panel dock contains some buttons which is used to show/hide left rela=
ted dock window. A button is expressed with a image which indicates the fun=
ction 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 assess=
ment of issues and opportunities with the dockable task pane.=20
[http://wiki.openoffice.org/wiki/AOO_Symphony_UX_Migration/Merge_Analysis_-=
_Task_Pane]

!sidebar.JPG|border=3D1!

*{+}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=3D1!
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 =E2=80=9Cdocument=
=E2=80=9D, =E2=80=9Cview=E2=80=9D, =E2=80=9Ctext=E2=80=9D, =E2=80=9Ctable=
=E2=80=9D, =E2=80=9Ccell=E2=80=9D etc{color}\\ |
| Binding \\ | Associate for dispatcher. To be a connector between dispatch=
er and context state. |
| Context | A specific situation, such as the current selection or cursor p=
osition in a document, has a context \\ |
| View frame(shell) \\ | View frame extended from shell. Context is represe=
nted by a stack of shell object |
| Interface \\ | Each interface has a static slot array |
| Slot \\ | Slot represents a command &nbsp; \\
2) contains function pointers to&nbsp; \\
execute the command or get \\
status information about it &nbsp;&nbsp; \\
3) has a unique slotID&nbsp; \\
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 fra=
mework 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:&nbsp;[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 ScTabeViewShel=
l. Child window factory will also be registered in application through ScPr=
opertyDockWinWrapper(extends from basic SfxChildWindow). Later the factory =
will be used to created property child window.


!window_registration.jpg|border=3D1!

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 t=
he first. Here panel dock class is named SfxTabbarWin. From the code view p=
icture, we can understand the process clearly. SfxFrame is a shell. Shell c=
reate panel dock window through SfxWorkWindow.

!panel_dock_creation.jpg|border=3D1!

3. Dock(Child) window creation

(1) Define&nbsp;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 =3D ChildWindowExecute ;

StateMethod =3D ChildWindowState ;

\]
{quote}

(3) state method definition and implementation(also part of slot)


{quote}
SfxBoolItem PropertyPanel SID_PROPERTY_SIDEBAR_DLG

\[

/\* flags: \*/

AutoUpdate =3D TRUE,

Cachable =3D Cachable,

FastCall =3D TRUE,

HasCoreId =3D FALSE,

HasDialog =3D FALSE,

ReadOnlyDoc =3D FALSE,

Toggle =3D FALSE,

Container =3D FALSE,

RecordAbsolute =3D FALSE,

RecordPerSet;

Synchron;

Readonly =3D FALSE,

/\* config: \*/

AccelConfig =3D TRUE,

MenuConfig =3D TRUE,

StatusBarConfig =3D FALSE,

ToolBoxConfig =3D TRUE,

GroupId =3D GID_FORMAT;

\]
{quote}

Its implementation is in the common shell =E2=80=9CSfxViewFrame: public Sfx=
Shell=E2=80=9D
{quote}
void &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; =
&nbsp; &nbsp;ChildWindowExecute(SfxRequest&);
{quote}

!docking_window_creation_1.jpg|border=3D1!

!docking_window_creation_2.jpg|border=3D1!

4. Property panel creation

Responsibility of PropertyPanel
* manage the life cycle of section =09control. AddSection(), RemoveSection(=
), ClearSections()
* layout each section(set each =09section's position and size).
* manage when to show or hide =09scrollbar, set size of the scroll window. =
Rearrange(), =09SetupScrollBars(), SetupVerticalScrollBar(), =09SetupHorizo=
ntalScrollBar(),&nbsp;scroll scrollBar, =09ScrollBarHandler()
* context switch, delegate the function to ContextSwitchHelper class
* maintain section state(expand/collapse) during context switch, delegate t=
he function to ContextSwitchHelper class

Responsibility of ContextSwitchHelper
* store the relationship of context =09and sections. map<ContextID, vector<=
SectionID>> =09macontext2sections, InitCtxt2SectionInfos().
* store section infos. =09vector<PanelSectionInfo>  maSectionInfos, InitSec=
tionInfos().
* context switch.  =09contextSwitch(ContextID)
* map<ContextID, =09SectioIDWithState> maDefaultStates, maContextStates;
* GetSectionState(), =09SetCurrentSectionState(), 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_PROPER=
TY_CONTEXT and SfxBindings and SfxDispatcher. This happens when property pa=
nel is creating

{quote}
mpCtxItem(new SfxPropertyContextItem(SID_SVX_PROPERTY_CONTEXT,*mpBindings,t=
his))
{quote}

!docking_window_creation_3.jpg|border=3D1!

5. Section creation with context sensitive

(1) Slot definition in sdi file

{quote}
SfxUInt16Item PropertyContextId SID_SVX_PROPERTY_CONTEXT

\[

/\* flags: \*/

AutoUpdate =3D TRUE,

Cachable =3D Cachable,

FastCall =3D TRUE,

HasCoreId =3D FALSE,

HasDialog =3D FALSE,

ReadOnlyDoc =3D FALSE,

Toggle =3D FALSE,

Container =3D FALSE,

RecordAbsolute =3D FALSE,

RecordPerSet;

Synchron;

Readonly =3D FALSE,

/\* config: \*/

AccelConfig =3D TRUE,

MenuConfig =3D TRUE,

StatusBarConfig =3D FALSE,

ToolBoxConfig =3D TRUE,

GroupId =3D GID_FORMAT;

\]
{quote}
(2) state method definition and implementation(also part of slot)

{quote}
SID_SVX_PROPERTY_CONTEXT

\[

StateMethod =3D GetPropertyContextId ;

\]//please pay attention that its interface is name Window.
{quote}
Its implementation is in the common shell =E2=80=9CSfxViewFrame: public Sfx=
Shell=E2=80=9D

{quote}
SAL_DLLPRIVATE void GetPropertyContextId( SfxItemSet &rSet );
{quote}
(3) If context is changed, dispatcher will call binding's update_Impl. In i=
t, 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) wi=
ndow creation" part.


!docking_window_creation_4.jpg|border=3D1!

!docking_window_creation_5.jpg|border=3D1!

Change your notification preferences: https://cwiki.apache.org/confluence/u=
sers/viewnotifications.action