Main Menu

WORK IN PROGRESS

This page is now outdated as the new Menu Navigation has been merged to trunk for the Alpha 0.2.22-1 release (End of October 2012). The page therefore needs updating and should not be relied on until this has happened.

The page is in the process of getting updated (January 2013).

General

MainWindowNew-generated.cs is the Main Menu Form.

• It gets displayed after a successful login.
• Its purpose is to allow the user to 'drill down' the OpenPetra Module and Menu hierarchy and to launch Tasks once the user navigated to the place in the Menu hierarchy where the Task is found.
• If the Main Menu Form is closed, the OpenPetra Client is closed.

The Main Menu Form content is highly dynamic. It is driven by content in the file \csharp\ICT\Petra\Definitions\UINavigation.yml - in other words, if the content of UINavigation.yml is changed, the content of the Main Menu Form gets changed (after an OpenPetra Client restart).

Control Hierarchy and Layout

Instantiation hierarchy of Controls hosted on the Main Menu Form:

Variable	Type	How the Control gets added
pnlContent	System.Windows.Forms.Panel	Hard-coded
--> pnlTaskArea	System.Windows.Forms.Panel	Hard-coded
----> pnlTop	System.Windows.Forms.Panel	Hard-coded
------> TopPanel	TPnlGradient {derives from System.Windows.Forms.Panel}	Dynamically
--------> FBreadcrumbTrailPanel	System.Windows.Forms.Panel	Dynamically
----------> BreadcrumbTrailModulePanel	System.Windows.Forms.Panel	Dynamically
------------> FBreadcrumbTrailModuleLabel	System.Windows.Forms.Label	Dynamically
----------> FBreadcrumbTrailDetailLabel	System.Windows.Forms.Label	Dynamically
----> dsbContent	TDashboard {derives from System.Windows.Forms.Panel}	Hard-coded
--> lstFolders	TLstFolderNavigation {derives from System.Windows.Forms.Panel}	Hard-coded
----> pnlMoreButtons	TPnlGradient {derives from System.Windows.Forms.Panel}	Hard-coded
----> sptNavigation	System.Windows.Forms.SplitContainer	Hard-coded
------> Panel1	System.Windows.Forms.SplitterPanel	Hard-coded
--------> CollPanelHoster [1..n]	TPnlModuleNavigation {derives from System.Windows.Forms.Panel}	Dynamically
------------> FCollapsibleNavigation	TPnlCollapsible {derives from System.Windows.Forms.UserControl}	Dynamically
--------------> FTaskListInstance OR	TTaskList {derives from System.Windows.Forms.UserControl}	Dynamically
--------------> FPnlCollapsibleHoster	TPnlCollapsibleHoster {derives from System.Windows.Forms.UserControl}	Dynamically
-----------------> CollPanel [1..n]	TPnlCollapsible {derives from System.Windows.Forms.UserControl}	Dynamically
-------------------> FTaskListInstance	TTaskList {derives from System.Windows.Forms.UserControl}	Dynamically
------------> FCurrentTaskList	TLstTasks {derives from System.Windows.Forms.UserControl}	Dynamically
--------------> TaskGroup [1..n]	TUcoTaskGroup {derives from System.Windows.Forms.UserControl}	Dynamically
----------------> flpTaskGroup	System.Windows.Forms.FlowLayoutPanel	Hard-coded
------------------> SingleTask [1..n]	TUcoSingleTask {derives from System.Windows.Forms.UserControl}	Dynamically
------> Panel2	System.Windows.Forms.SplitterPanel	Hard-coded
--------> rbt + Module Name [1..n]	TRbtNavigationButton {derives from Owf.Controls.A1Panel}	Dynamically

Note: The instantiation path does not always correlate with the nesting of Controls in each other! The nesting is described in the section 'Description/Purpose'.

Description/Purpose:

• pnlContent: contains lstFolders and pnlTaskArea Controls.
  • The only other Controls on the Main Menu Form are mnuMain (the Menu) and stbMain (the Status Bar); pnlContent takes up the rest of the space of the Form (DockStyle.Fill).
  • pnlContent is not really seen on the Main Menu Form, although it is a Panel.
• pnlTaskArea: Fills the entire Main Menu Form space that lies right of the lstFolders Control (DockStyle.Fill) and contains the pnlTop and dsbContent Controls.
  • pnlTaskArea is not really seen on the Main Menu Form, although it is a Panel.
• pnlTop: Is placed above the dsbContent Control and right of the lstFolders Control (DockStyle.Top).
  • Hosts only a TPnlGradient Control, TopPanel, which itself is hosting Controls for the displaying of the 'Breadcrumb Trail'.
  • TopPanel is dynamically created as the WinForm Generator does not support TPnlGradient Controls. Therefore the Control hierarchy inside TopPanel (four Controls in total) is dynamically created as well (in the Constructor of TBreadcrumbTrail).
• dsbContent (TDashboard Control): Fills the entire space (DockStyle.Fill) that lies under the pnlTop Control (and right of the lstFolders Control).
  • Hosts 1..n TLstTasks instances (as many as the user has navigated to by navigating through the Sub-Modules) which get instantiated from within TPnlModuleNavigation.
  • Only one TLstTasks instance is seen at a given time (the one held in FCurrentTaskList)!
  • dsbContent is not really seen on the Main Menu Form, although it is a Panel.
• lstFolders (TLstFolderNavigation Control): Is placed on the left side of the Main Menu Form (DockStyle.Left) and therefore to the left of the dsbContent Control.
  • Hosts a SplitContainer which hosts...
    • 1..n TPnlModuleNavigation Controls, one per OpenPetra Module.
      • TPnlModuleNavigation instances are shown above the TRbtNavigationButton Constrols (inside the SplitContainer's Splitter Panel #1 (sptNavigation.Panel1)).
      • Once an instance of TPnlModuleNavigation got created and added to the Controls of sptNavigation.Panel1 it is re-used once the user switches to it again!
      • Only one TPnlModuleNavigation instance is seen at a given time (the one held in CollPanelHoster)!
    • 1..n TRbtNavigationButton Controls, each representing an OpenPetra Module. These are shown below the TPnlModuleNavigation instances (inside the SplitContainer's Splitter Panel #2 (sptNavigation.Panel2)).
  • Also hosts a Panel that has currently no functionality (pnlMoreButtons). It is displayed below the SplitContainer.
• TPnlModuleNavigation Controls:
  • contain a single instance of a TPnlCollapsible Control (FCollapsibleNavigation) which collapses in horizontal direction and on doing so reduces the width of the lstFolders Control to a fraction of it's usual width, making more space available for the pnlTaskArea Control.
    • the heading of the TPnlCollapsible Control shows the current OpenPetra Module
    • only one TPnlModuleNavigation instance is seen at a given time!
  • also hold a reference to the currently displayed TLstTasks Control in FCurrentTaskList
    • although there can be 1..n TLstTasks Controls per Sub-Module, only one is currently displayed
• TPnlCollapsible Controls are 'Collapsible Panels'
  • have a heading
  • can host either
    • a TTaskList Control OR
    • a TPnlCollapsibleHoster Control
    • (TPnlCollapsible can host an arbitrary UserControl, too, but that is not discussed here as it isn't used in the Module Navigation).
  • which Control it hosts when: see description for Control 'TPnlCollapsibleHoster'.
  • can be collapsed/expanded in either horizontal or vertical direction
    • collapsing/expanding is triggered by either clicking the 'collapse/expand button' or the heading
• TTaskList Controls contain 1..n 'Tasks' which are represented by LinkLabels
  • The 'Tasks' represent the individual Sub-Modules of OpenPetra
  • Once a 'Task' is clicked the TTaskList's 'ItemActivation' Event is fired. That causes the OnItemActivation Method of TPnlModuleNavigation to run, which in turn runs the Method 'LinkClicked', which creates or retrieves the associated TLstTasks Control, stores it in FCurrentTaskList and runs the code 'FDashboard.ShowTaskList(FCurrentTaskList);' which shows that TLstTasks Control to the user in the dsbContent Control.
• TLstTasks Controls manage and display SingleTasks within TaskGroups in the dsbContent Control.
  • although there can be 1..n TLstTasks Controls per Sub-Module, only one is currently displayed!
• TPnlCollapsibleHoster Controls contains 1..n TPnlCollapsible Controls
  • several TPnlCollapsible Controls can be expanded in vertical direction at the same time
  • TPnlCollapsibleHoster Controls are only needed for Sub-Modules that either
    • have many Tasks and the Tasks should therefore get grouped into 1..n TPnlCollapsible Controls (System Manager Module);
    • for the Finance and Financial Development Modules in case the OpenPetra Site has got more than one Ledger.
      • If this is so then a 'Select Ledger' TPnlCollapsible Controls is dynamically added, listing all available Ledgers as Tasks, and the Sub-Modules of the Finance Module are put in a dynamically added 'Finance' TPnlCollapsible Control.
  • usually, only one Sub-Module (=LinkLabel) can be active (=underlined LinkLabel). This can be changed by setting Property 'OnlyOneActiveTaskOnAllCollapsiblePanelsTaskLists' to false, but this is only done for the Finance and Financial Development Modules in case the OpenPetra Site has got more than one Ledger - to allow a Ledger to be selected plus a Sub-Module as well.
• TaskGroup (TUcoTaskGroup Control): Groups several SingleTasks into groups.
  • Each Task Group features a heading and a dividing line.
  • Each Task Group contains a flpTaskGroup Control.
  • Example: 'New Partner' Group in Partner Module, Partners Sub-Module.
• flpTaskGroup (FlowLayoutPanel Control): Responsible for the layout of SingleTasks in TaskGroups.
  • Example: Layout of the SinlgeTasks 'Add New Family', 'Add New Person' and 'Add New Organisation' in the 'New Partner' Group in the Partner Module, Partners Sub-Module.
• SingleTask (TUcoSingleTask Control): A single Main Menu item that the user can click to perform a Task in OpenPetra.
  • Example: 'Add New Family' in 'New Partner' Group in Partner Module, Partners Sub-Module.

Annotated Screenshots

Module/Sub-Module Navigation – Module-level collapsing only

Module/Sub-Module Navigation – Module-level and Submodule-level collapsing

Task Area