KWWidgets
debian/tmp/usr/include/KWWidgets/vtkKWUserInterfacePanel.h
Go to the documentation of this file.
1 /*=========================================================================
2 
3  Module: $RCSfile: vtkKWUserInterfacePanel.h,v $
4 
5  Copyright (c) Kitware, Inc.
6  All rights reserved.
7  See Copyright.txt or http://www.kitware.com/Copyright.htm for details.
8 
9  This software is distributed WITHOUT ANY WARRANTY; without even
10  the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
11  PURPOSE. See the above copyright notice for more information.
12 
13 =========================================================================*/
14 // .NAME vtkKWUserInterfacePanel - a user interface panel.
15 // .SECTION Description
16 // This class is used to abstract the way an interface "panel" can be
17 // subdivided into "pages" (i.e. "sections"). It allows specific GUI parts of
18 // an application to be encapsulated inside independent panels. Panels are
19 // then associated to a user interface manager (see vtkKWUserInterfaceManager)
20 // which is responsible for grouping them inside a widget and handling user
21 // interaction so that panels and their pages can be selected in more or less
22 // fancy ways. If the user interface manager uses a notebook under the hood,
23 // then this class is likely to receive a notebook's page when it will request
24 // for a page from the manager. If the manager chooses for a flat GUI, then
25 // this class is likely to receive a simple frame that will be stacked by the
26 // manager on top of other pages.
27 // This class is not a widget, it can not be mapped, the manager is the
28 // place where a concrete widget is set and used as the root of all panels (see
29 // vtkKWUserInterfaceManagerNotebook for example). What you need to do
30 // is to set the UserInterfaceManager's Ivar to a manager, and the rest should
31 // be taken care of (i.e. the panel is automatically added to the manager,
32 // and if the panel is not created the first time one if its pages is shown or
33 // raised, the panel's Create() method is automatically called by the manager,
34 // allowing the creation of the panel to be delayed until it is really needed).
35 // You should not use the manager's API to add the panel, add or raise pages,
36 // etc, just use this panel's API and calls will be propagated to the
37 // right manager with the proper arguments).
38 // .SECTION See Also
39 // vtkKWUserInterfaceManager vtkKWUserInterfaceManagerNotebook
40 
41 #ifndef __vtkKWUserInterfacePanel_h
42 #define __vtkKWUserInterfacePanel_h
43 
44 #include "vtkKWObject.h"
45 
46 class vtkKWIcon;
48 class vtkKWWidget;
49 
51 {
52 public:
53  static vtkKWUserInterfacePanel* New();
54  vtkTypeRevisionMacro(vtkKWUserInterfacePanel,vtkKWObject);
55  void PrintSelf(ostream& os, vtkIndent indent);
56 
57  // Description:
58  // Set the user interface manager. This automatically adds the
59  // panel to the manager. If you want to remove this panel from the manager,
60  // set the manager to NULL (it is done automatically by the destructor),
61  // or call RemovePanel from the manager so that you can add it back later.
62  // Note that ownership is transferred to the manager by incrementing
63  // (and decrementing later on) the ref count of the panel in
64  // vtkKWUserInterfaceManager's AddPanel and RemovePanel methods.
65  virtual void SetUserInterfaceManager(vtkKWUserInterfaceManager*);
66  vtkGetObjectMacro(UserInterfaceManager, vtkKWUserInterfaceManager);
67 
68  // Description:
69  // Set the panel name. Can be used to add the panel to a menu, etc.
70  vtkGetStringMacro(Name);
71  vtkSetStringMacro(Name);
72 
73  // Description:
74  // Create the interface objects. Note that if the panel is not created
75  // the first time one if its pages is shown or raised, this method is
76  // automatically called by the manager, allowing the creation of the
77  // panel to be delayed until it is really needed. In the same way, if
78  // the user interface manager has not been created at this point, it
79  // is automatically created now (see vtkKWUserInterfaceManager::Create()).
80  virtual void Create();
81  virtual int IsCreated();
82 
83  // Description:
84  // Enable/Disable this panel. This should propagate SetEnabled() calls to the
85  // internal widgets.
86  virtual void SetEnabled(int);
87  vtkBooleanMacro(Enabled, int);
88  vtkGetMacro(Enabled, int);
89 
90  // Description:
91  // Add/remove a page to/from the panel (this will, in turn, instructs the
92  // manager to reserve or remove a page for this given panel).
93  // balloon specifies the balloon help for that page, icon is an optional
94  // icon in case it is supported by the manager later on.
95  // Return a unique positive ID for the page that was reserved/removed,
96  // or < 0 on error.
97  virtual int AddPage(const char *title,
98  const char *balloon = 0,
99  vtkKWIcon *icon = 0);
100  virtual int RemovePage(const char *title);
101 
102  // Description:
103  // Set a page's title, balloon help and icon.
104  virtual void SetPageTitle(int id, const char *title);
105  virtual void SetPageBalloonHelpString(int id, const char *str);
106  virtual void SetPageIcon(int id, vtkKWIcon *icon);
107  virtual void SetPageIconToPredefinedIcon(int id, int icon_index);
108 
109  // Description:
110  // Retrieve the widget corresponding to a given page added to the panel.
111  // This can be done through the unique page ID, or using the page title.
112  // The user UI components should be inserted into this widget.
113  // Return NULL on error.
114  virtual vtkKWWidget *GetPageWidget(int id);
115  virtual vtkKWWidget *GetPageWidget(const char *title);
116 
117  // Description:
118  // Retrieve the parent widget of the pages associated to the panel. It is
119  // the unique widget that is common to all pages in the chain of parents.
120  virtual vtkKWWidget *GetPagesParentWidget();
121 
122  // Description:
123  // Raise a page added to the panel. This can be done through the unique
124  // page ID, or using the page title. Note that if the panel has not been
125  // created at this point, the manager will call the panel's Create()
126  // method automatically, allowing the creation of the panel to be delayed
127  // until it is really needed.
128  virtual void RaisePage(int id);
129  virtual void RaisePage(const char *title);
130 
131  // Description:
132  // Show a panel. It will make sure the pages added to this panel are shown.
133  // Note that if the panel has not been created at this point, the manager
134  // will call the panel's Create() method automatically, allowing the
135  // creation of the panel to be delayed until it is really needed.
136  // Raise() behaves like Show(), but it will also instruct the manager to
137  // bring up the first page of the panel to the front.
138  // IsVisible() will check if the pages of this panel are visible/shown.
139  // Return 1 on success, 0 on error.
140  virtual int Show();
141  virtual int Raise();
142  virtual int IsVisible();
143 
144  // Description:
145  // Refresh the interface.
146  virtual void Update();
147 
148  // Description:
149  // Update the "enable" state of the object and its internal parts.
150  // Depending on different Ivars (this->Enabled, the application's
151  // Limited Edition Mode, etc.), the "enable" state of the object is updated
152  // and propagated to its internal parts/subwidgets. This will, for example,
153  // enable/disable parts of the widget UI, enable/disable the visibility
154  // of 3D widgets, etc.
155  virtual void UpdateEnableState() {};
156 
157 protected:
160 
162 
163  char *Name;
164 
165 private:
166 
167  int Enabled;
168  int PanelIsCreated;
169 
170  vtkKWUserInterfacePanel(const vtkKWUserInterfacePanel&); // Not implemented
171  void operator=(const vtkKWUserInterfacePanel&); // Not Implemented
172 };
173 
174 #endif
175