PaletteRefUtils.h

//========================================================================================
// 
// $File$
// 
// Owner: Dave Burnard
// 
// $Author$
// 
// $DateTime$
// 
// $Revision$
// 
// $Change$
// 
// Copyright 1997-2010 Adobe Systems Incorporated. All rights reserved.
// 
// NOTICE: Adobe permits you to use, modify, and distribute this file in accordance 
// with the terms of the Adobe license agreement accompanying it. If you have received
// this file from a source other than Adobe, then your use, modification, or 
// distribution of it requires the prior written permission of Adobe.
// 
//========================================================================================

#ifndef __PaletteRefUtils__
#define __PaletteRefUtils__

#include "PaletteRef.h"
#include "IUserInterfacePreferences.h"

class IDocumentPresentation;

class PaletteRefUtils
{
 // ======== PaletteRef API ======== 
 public:

 enum DockLocation
 {
 kLeft_DockLocation = 1, 
 kTop_DockLocation, 
 kRight_DockLocation, 
 kBottom_DockLocation, 
 kFloating_DockLocation, 
 kAppContainer_DockLocation 
 };

 enum DockMode
 {
 kExpanded_DockMode = 1, 
 kConcealed_DockMode, 
 kRevealed_DockMode 
 };

 enum TabPaneMode
 {
 kExpanded_TabPaneMode = 1, 
 kIcon_TabPaneMode 
 };
 
 enum TabPaneLayoutMode
 {
 kAutoFlow_TabPaneLayoutMode = 1, 
 kManual_TabPaneLayoutMode 
 };
 
 
 enum ToolbarSizeVariant
 {
 kVerticalWide_ToolbarSizeVariant = 1, 
 kVerticalNarrow_ToolbarSizeVariant, 
 kHorizontal_ToolbarSizeVariant
 };

 //
 // ----- Methods to test the type of a Palette.
 //
 static bool16 IsRootPaletteNode(const PaletteRef& whichPalette);

 static bool16 IsApplicationContainer(const PaletteRef& whichPalette);

 static bool16 IsDock(const PaletteRef& whichPalette);

 //static bool16 IsTabGroupCluster(const PaletteRef& whichPalette);
 
 static bool16 IsTabbedPaletteDock(const PaletteRef& whichPalette);

 static bool16 IsDocumentDock(const PaletteRef& whichPalette);

 static bool16 IsFloatingTabbedPaletteDock(const PaletteRef& whichPalette);

 static bool16 IsFloatingDocumentDock(const PaletteRef& whichPalette);

 static bool16 IsTabPane(const PaletteRef& whichPalette);

 static bool16 IsControlBarPane(const PaletteRef& whichPalette);

 static bool16 IsTabGroup(const PaletteRef& whichPalette);

 static bool16 IsToolbar(const PaletteRef& whichPalette);

 static bool16 IsControlBar(const PaletteRef& whichPalette);

 static bool16 IsTabPanelContainer(const PaletteRef& whichPalette);

 static bool16 IsDocumentPresentation(const PaletteRef& whichPalette);

 //static bool16 IsTopLevelPalette(const PaletteRef& whichPalette);
 
 static bool16 IsPaletteFloating(const PaletteRef& whichPalette);

 static PaletteRef GetPaletteRefFromOWLPalette(OWLControlRef owlControl);
 
 static IDocumentPresentation* GetDocumentPresentationFromPaletteRef(const PaletteRef& presentationRef);

 static PaletteRef GetPaletteRefFromDocumentPresentation(const IDocumentPresentation* pres);

 //
 // ----- Palette hierarchy enumeration methods.
 // Use these methods to traverse the palette hierarchy.
 //
 static PaletteRef GetRootPaletteNode();

 static PaletteRef GetApplicationContainer();

 static void SetApplicationContainer(OWLControlRef owlControl);

 static PaletteRef GetApplicationContainerDocumentDock();

 static uint16 GetChildCountOfPalette(const PaletteRef& parentPalette);

 static PaletteRef GetNthChildOfPalette(const PaletteRef& parentPalette, uint16 inIndex);

 static PaletteRef GetParentOfPalette(const PaletteRef& whichPalette);

 static void ReparentPalette(const PaletteRef& whichPalette, const PaletteRef& newParent, const PaletteRef& beforeSibling);

 static void FloatPalette(const PaletteRef& whichPalette);

#if MACINTOSH 
 //
 // ----- AppFrame Embedding. 
 //
 static bool16 IsAppFrameEmbeddingOnMacEnabled();
 static void SetAppFrameEmbeddingOnMacEnabled(bool16 enabledState = kTrue);
#endif

 //
 // ----- Finding the TopLevel Palettes (i.e. not contained in another palette type). 
 //
 static uint16 GetTopLevelPaletteCount();
 static PaletteRef GetNthTopLevelPalette(uint16 inIndex);

 //
 // ----- Finding the Docks. 
 //
 static uint16 GetDockCount();
 static PaletteRef GetNthDock(uint16 inIndex);
 static PaletteRef FindDockByLocation(DockLocation whichLocation);

 //
 // ----- Finding Floating TabbedPalette Docks. 
 //
 static uint16 GetFloatingTabbedPaletteDockCount();
 static PaletteRef GetNthFloatingTabbedPaletteDock(uint16 inIndex);

 //
 // ----- Finding Floating Document Docks. 
 //
 static uint16 GetFloatingDocumentDockCount();
 static PaletteRef GetNthFloatingDocumentDock(uint16 inIndex);
 static PaletteRef GetFloatingDocumentDockParentOfDocument(PaletteRef whichDocument);
 
 //
 // ----- Dock Accessors. 
 //
 static DockLocation GetDockLocation(const PaletteRef& whichDock);
 static DockMode GetDockMode(const PaletteRef& whichDock);
 static void SetDockMode(const PaletteRef& whichDock, DockMode newMode);
 static SysPoint GetFloatingDockPreferredPosition(const PaletteRef& whichDock);
 static void SetFloatingDockPreferredPosition(const PaletteRef& whichDock, SysPoint& where);
 static void SetFloatingDocumentWindowBounds(const PaletteRef& documentRef, SysRect newBounds);
 static void SetFloatingDocumentBounds(const PaletteRef& documentRef, SysPoint newDimensions);

 //
 // ----- Finding the TabPanes. 
 // TabPanes are found by enumerating the children of a dock and testing with IsTabPane 
 //
 static TabPaneMode GetTabPaneMode(const PaletteRef& whichTabPane);
 static void SetTabPaneMode(const PaletteRef& whichTabPane, TabPaneMode newMode);

 static TabPaneLayoutMode GetTabPaneLayoutMode(const PaletteRef& whichTabPane);
 static void SetTabPaneLayoutMode(const PaletteRef& whichTabPane, TabPaneLayoutMode newLayoutMode);

 static float GetTabPanePreferredIconicWidth(const PaletteRef& whichTabPane);
 static void SetTabPanePreferredIconicWidth(const PaletteRef& whichTabPane, float newWidth);

 //
 // ----- Finding the Toolbars and ControlBars. 
 // There are a bit trickier to find since they can be either floating or docked. 
 // So enumerate the appropriate parent and check each child with IsToolbar or IsControlBar
 //

 //
 // ----- Toolbar Accessors. 
 //
 static ToolbarSizeVariant GetToolbarSizeVariant(const PaletteRef& whichToolbar);
 static void SetToolbarSizeVariant(const PaletteRef& whichToolbar, ToolbarSizeVariant newVariant);
 static void SetToolbarSizeVariant(const PaletteRef& toolbarRef, IUserInterfacePreferences::ToolboxState newState);
 
 static void FixupToolbarContentOrigin(const PaletteRef& toolbarRef);

 //
 // ----- Palette Labels. 
 //
 enum PanelLabel {
 kTitle_PanelLabel = 0, // Title (e.g. used for tabs)
 kTooltip_PanelLabel, // Tooltip
 };
 
 static PMString GetPaletteLabel(const PaletteRef& whichPalette, PanelLabel whichLabel = kTitle_PanelLabel);
 static void SetPaletteLabel(const PaletteRef& whichPalette, const PMString& labelstr, PanelLabel whichLabel = kTitle_PanelLabel);

 //
 // ----- Palette Positioning (always global coordinates). 
 //
 static SysPoint GetPalettePosition (const PaletteRef& whichPalette);
 
 static void SetPalettePosition (const PaletteRef& whichPalette, SysCoord left, SysCoord top);

 
 static SysRect GetPaletteBounds (const PaletteRef& whichPalette);

 static void SetPaletteSize (const PaletteRef& whichPalette, SysPoint newDimensions);
 
 static SysRect GetOpticalPaletteBounds (const PaletteRef& whichPalette);
 

 //
 // ----- Palette Visibility
 //
 static bool16 GetVisibleState (const PaletteRef& whichPalette);
 static bool16 IsPaletteVisible (const PaletteRef& whichPalette);

 static bool16 IsPaletteMinimized (const PaletteRef& whichPalette);
 static void ChangePaletteMinimization (const PaletteRef& whichPalette, bool16 minimize);
 
 enum PaletteVisibilityChange { kShowPalette = 0, kHidePalette };
 
 static void ShowHideEntirePaletteSystem(PaletteVisibilityChange show);
 
 static bool16 IsEntirePaletteSystemHidden();
 
 static void ForcePaletteSystemToPerformLayout();

 
 static void ShowHidePalette (const PaletteRef& whichPalette, PaletteVisibilityChange show);
 
 static void BringPaletteToFront(const PaletteRef& whichPalette);
 
 static void CenterPaletteOnScreen(const PaletteRef& whichPalette);

 //
 // ----- Palette Creation Shortcuts.
 // @see IPaletteFactory
 //
 static PaletteRef NewTabPaneInDock(const PaletteRef& dockParent, TabPaneMode mode, const PaletteRef& beforeOptionalSibling);

 static PaletteRef NewControlBarPaneInDock(const PaletteRef& dockParent, const PaletteRef& beforeOptionalSibling);

 static PaletteRef NewFloatingTabGroupContainerPalette();

 static PaletteRef NewTabGroupPalette(const PaletteRef& tabGroupClusterOrTabPaneParent); 

 static PaletteRef NewToolbarPalette();

 static PaletteRef NewControlbarPalette();
 
 //
 // ----- Palette Closed state.
 // The closed state reflects how a palette is marked when the user clicks on the close box of a palette.
 // It is included in the effective visibility calculation.
 //
 static bool16 CanClose(const PaletteRef& paletteRef);
 static bool16 GetIsClosed(const PaletteRef& paletteRef);
 static void ChangeIsClosed(const PaletteRef& paletteRef, bool16 close = kTrue);
 
 static void AdjustClientAreaToPalettes();
 
 static void InvalidateAllPalettes();

#ifdef DEBUG

 static char* GetPaletteTypeString(PaletteRefType palType);
 static void DumpPaletteHierarchy(const PaletteRef& pal);
 static void DumpOWLWidgetHierarchy();
#endif

 enum ShowHideLevel {
 kShowHideFloatingTabPalettes,
 kShowHideAllPalettes
 };
 
 static void ShowHidePalettes(ShowHideLevel paletteShowHideLevel = kShowHideAllPalettes);
 
 enum WhichTabPanes {
 kNoTabPanes,
 kLHSTabPanes,
 kRHSTabPanes,
 kAllTabPanes
 };
 
 static bool16 AreTabPanesOpen(WhichTabPanes whichOnes = kAllTabPanes);
 static void OpenCloseTabPanes(WhichTabPanes whichOnes = kAllTabPanes, bool16 open = kTrue); 
 
 static IXMLGenerator* QueryXMLGenerator(PaletteRefType paletteType);
 static IPaletteFactory* QueryPaletteFactory(PaletteRefType paletteType);
 
 static void NotifyPaletteIsClosing(PaletteRef owlPalette);

 static void NotifyPaletteContainerIsClosing(PaletteRef owlPalette);

 static void PositionPaletteOnScreen(const PaletteRef& whichPalette, PMReal distanceFromLeftOnScreenInPercentage);

private:

 static bool16 fgAllTabPanesOpen;
 static bool16 fgRHSTabPanesOpen;
 static bool16 fgLHSTabPanesOpen;
 
 static PaletteRef fgApplicationContainer;
};

#endif // __PaletteRefUtils__