KWWidgets
debian/tmp/usr/include/KWWidgets/vtkKWSelectionFrameLayoutManager.h
Go to the documentation of this file.
1 /*=========================================================================
2 
3 Copyright (c) 1998-2003 Kitware Inc. 469 Clifton Corporate Parkway,
4 Clifton Park, NY, 12065, USA.
5 
6 All rights reserved. No part of this software may be reproduced, distributed,
7 or modified, in any form or by any means, without permission in writing from
8 Kitware Inc.
9 
10 IN NO EVENT SHALL THE AUTHORS OR DISTRIBUTORS BE LIABLE TO ANY PARTY FOR
11 DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT
12 OF THE USE OF THIS SOFTWARE, ITS DOCUMENTATION, OR ANY DERIVATIVES THEREOF,
13 EVEN IF THE AUTHORS HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
14 
15 THE AUTHORS AND DISTRIBUTORS SPECIFICALLY DISCLAIM ANY WARRANTIES, INCLUDING,
16 BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
17 PARTICULAR PURPOSE, AND NON-INFRINGEMENT. THIS SOFTWARE IS PROVIDED ON AN
18 "AS IS" BASIS, AND THE AUTHORS AND DISTRIBUTORS HAVE NO OBLIGATION TO PROVIDE
19 MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
20 
21 =========================================================================*/
22 // .NAME vtkKWSelectionFrameLayoutManager - a MxN layout manager for a set of vtkKWSelectionFrame
23 // .SECTION Description
24 // This class is a layout manager for vtkKWSelectionFrame. It will grid them
25 // according to a given MxN resolution, allocate new ones, handle
26 // print/screenshots, etc.
27 // Note that the selection frame can be given any position, the resolution
28 // and the origin of the layout manager are actually the parameters that
29 // specify which one are visible. For example, one can set 4 widgets on
30 // a 2x2 grid, set the resolution to 1x1, but set the origin at (0,0) or
31 // (1,1) to zoom on a specific widget.
32 
33 #ifndef __vtkKWSelectionFrameLayoutManager_h
34 #define __vtkKWSelectionFrameLayoutManager_h
35 
36 #include "vtkKWCompositeWidget.h"
37 
39 class vtkKWSelectionFrameLayoutManagerInternals;
40 class vtkKWRenderWidget;
41 class vtkImageData;
42 class vtkKWMenu;
43 class vtkKWToolbar;
44 class vtkKWFrame;
45 
47 {
48 public:
51  void PrintSelf(ostream& os, vtkIndent indent);
52 
53  // Description:
54  // Set/Get the resolution of the layout (number of columns, number of rows).
55  virtual void SetResolution(int nb_cols, int nb_rows);
56  virtual void SetResolution(int res[2])
57  { this->SetResolution(res[0], res[1]); };
58  vtkGetVector2Macro(Resolution, int);
59 
60  // Description:
61  // Set/Get the origin of the layout (column, row), i.e. where to start
62  // displaying widget from in the virtual grid on which they are set.
63  virtual void SetOrigin(int col, int row);
64  virtual void SetOrigin(int origin[2])
65  { this->SetOrigin(origin[0], origin[1]); };
66  vtkGetVector2Macro(Origin, int);
67 
68  // Description:
69  // Add a new selection frame to the pool
70  // This will call Register() on the widget (increasing its ref count).
71  // Return 1 on success, 0 otherwise
72  virtual int AddWidget(vtkKWSelectionFrame *widget);
73  virtual int AddWidgetWithTagAndGroup(
74  vtkKWSelectionFrame *widget, const char *tag, const char *group);
75 
76  // Description:
77  // Allocate a new selection frame and add it to the pool.
78  // Return the allocated widget, or NULL on error
79  virtual vtkKWSelectionFrame* AllocateAndAddWidget();
80 
81  // Description:
82  // Set the widget's tag in the pool.
83  // This provide an alternate way of accessing the widget in the pool.
84  // Note that this is *not* the title of the frame, as set using the
85  // vtkKWSelectionFrame::SetTitle method.
86  // If several widgets have the same tag, the first one is usually
87  // retrieved. No constraints is put on the uniqueness of the tag.
88  // Return 1 on success, 0 on error
89  virtual int SetWidgetTag(vtkKWSelectionFrame*, const char *tag);
90  virtual const char* GetWidgetTag(vtkKWSelectionFrame*);
91 
92  // Description:
93  // Set the widget's group in the pool.
94  // This provide an way of grouping widgets logicaly in the pool.
95  // Return 1 on success, 0 on error
96  virtual int SetWidgetGroup(vtkKWSelectionFrame*, const char *group);
97  virtual const char* GetWidgetGroup(vtkKWSelectionFrame*);
98 
99  // Description:
100  // Get the number of widgets in the pool
101  virtual int GetNumberOfWidgets();
102  virtual int GetNumberOfWidgetsWithTag(const char *tag);
103  virtual int GetNumberOfWidgetsWithGroup(const char *group);
104 
105  // Description:
106  // Query if widget is in the pool
107  virtual int HasWidget(vtkKWSelectionFrame *widget);
108  virtual int HasWidgetWithTag(const char *tag);
109  virtual int HasWidgetWithTagAndGroup(const char *tag, const char *group);
110 
111  // Description:
112  // Retrieve a widget given its tag (as set using SetWidgetTag()), its
113  // tag and group, its title (as set using vtkKWSelectionFrame::SetTitle),
114  // its rank in the pool (n-th widget), or its rank (n-th widget) but not
115  // matching another widget 'avoid'.
116  // Return the widget, or NULL if not found
117  virtual vtkKWSelectionFrame* GetWidgetWithTag(const char *tag);
118  virtual vtkKWSelectionFrame* GetWidgetWithTagAndGroup(
119  const char *tag, const char *group);
120  virtual vtkKWSelectionFrame* GetWidgetWithTitle(const char *title);
121  virtual vtkKWSelectionFrame* GetNthWidget(int index);
122  virtual vtkKWSelectionFrame* GetNthWidgetNotMatching(
123  int index, vtkKWSelectionFrame *avoid);
124  virtual vtkKWSelectionFrame* GetNthWidgetWithGroup(
125  int index, const char *group);
126 
127  // Description:
128  // Set/Get position of widget.
129  // Note that the position is independent of the resolution, you can
130  // still set the position of a widget anywhere while displaying only
131  // a subset of the largest grid encompassing all widgets (i.e. you can
132  // set a widget at (2, 3), i.e. third column, fourth row, but set the
133  // resolution to (1, 1) to display only the first column and first row: the
134  // next time the resolution is set to, say, (4, 4), the widget at (2, 3)
135  // will be shown).
136  // Changing the position of a widget will repack the layout (call to Pack()).
137  // If you need to change the position of a lot of widgets without repacking
138  // each time, try SetImmediateWidgetPosition(), and Pack().
139  // Return 1 (or widget) on success (and if the position was really changed),
140  // 0 (or NULL) on error.
141  virtual int GetWidgetPosition(vtkKWSelectionFrame *w, int *col, int *row);
142  virtual int GetWidgetPosition(vtkKWSelectionFrame *w, int pos[2])
143  { return this->GetWidgetPosition(w, pos, pos + 1); }
144  virtual int SetWidgetPosition(vtkKWSelectionFrame *w, int col, int row);
145  virtual int SetWidgetPosition(vtkKWSelectionFrame *w, int pos[2])
146  { return this->SetWidgetPosition(w, pos[0], pos[1]); }
147  virtual vtkKWSelectionFrame* GetWidgetAtPosition(int col, int row);
148  virtual vtkKWSelectionFrame* GetWidgetAtPosition(int pos[2])
149  { return this->GetWidgetAtPosition(pos[0], pos[1]); }
150 
151  // Description:
152  // Switch widgets position (set the position of two widgets)
153  // Return 1 (or widget) on success, 0 (or NULL) on error
154  virtual int SwitchWidgetsPosition(
156 
157  // Description:
158  // Reorganize the widgets position automatically (for example, to try
159  // to avoid empty spaces).
160  vtkBooleanMacro(ReorganizeWidgetPositionsAutomatically, int);
161  virtual void SetReorganizeWidgetPositionsAutomatically(int);
162  vtkGetMacro(ReorganizeWidgetPositionsAutomatically, int);
163 
164  // Description:
165  // Set/Get the maximum resolution of the layout
166  // (number of columns, number of rows).
167  virtual void SetMaximumResolution(int nb_cols, int nb_rows);
168  virtual void SetMaximumResolution(int res[2])
169  { this->SetMaximumResolution(res[0], res[1]); };
170  vtkGetVector2Macro(MaximumResolution, int);
171 
172  // Description:
173  // Return if a specific widget is visible at this point, i.e. mapped
174  // on screen at a specific position given the current resolution.
175  virtual int GetWidgetVisibility(vtkKWSelectionFrame *w);
176 
177  // Description:
178  // Check if a widget is maximized, i.e. at position (0,0) in a (1,1)
179  // resolution. Maximize it (this will save the old resolution and position)
180  // or undo maximize (this will restore old resolution and position).
181  // Toggle maximize will maximize if widget is not maximized already or undo
182  // the maximize
183  // Return 1 on success, 0 on error
184  virtual int IsWidgetMaximized(vtkKWSelectionFrame *w);
185  virtual int MaximizeWidget(vtkKWSelectionFrame *w);
186  virtual int UndoMaximizeWidget();
187  virtual int ToggleMaximizeWidget(vtkKWSelectionFrame *w);
188 
189  // Description:
190  // Select a a widget.
191  // If arg is NULL, nothing is selected (all others are deselected)
192  virtual void SelectWidget(vtkKWSelectionFrame *widget);
193 
194  // Description:
195  // Get the selected widget.
196  // Return the widget, or NULL if none is selected
197  virtual vtkKWSelectionFrame* GetSelectedWidget();
198 
199  // Description:
200  // Specifies a command to associate with the widget. This command is
201  // typically invoked when the selection is changed.
202  // The 'object' argument is the object that will have the method called on
203  // it. The 'method' argument is the name of the method to be called and any
204  // arguments in string form. If the object is NULL, the method is still
205  // evaluated as a simple command.
206  virtual void SetSelectionChangedCommand(
207  vtkObject *object, const char *method);
208  vtkGetStringMacro(SelectionChangedCommand);
209 
210  // Description:
211  // Remove a widget, or all of them, or all of the widgets in a group.
212  // This will call each widget's Close() method, and UnRegister() it.
213  // Return 1 on success, 0 on error
214  virtual int RemoveWidget(vtkKWSelectionFrame *widget);
215  virtual int RemoveAllWidgets();
216  virtual int RemoveAllWidgetsWithGroup(const char *group);
217 
218  // Description:
219  // Try to show all the widgets belonging to a specific group.
220  // This method will check if the visible widgets belong to the group,
221  // and exchange change if this is not the case.
222  // Return 1 on success, 0 on error
223  virtual int ShowWidgetsWithGroup(const char *group);
224 
225  // Description:
226  // Save all widgets into an image (as a screenshot) or into the
227  // clipboard (win32). If no filename, the user is prompted for one
228  // (provided that this widget is part of a window).
229  // Return 1 on success, 0 otherwise
230  // GetRenderWidget() need to be implemented accordingly.
231  virtual int SaveScreenshotAllWidgets();
232  virtual int SaveScreenshotAllWidgetsToFile(const char* fileName);
233  virtual int CopyScreenshotAllWidgetsToClipboard();
234 
235  // Description:
236  // Append widgets to image data.
237  // The 'Fast' version of each method does not set the render widget to
238  // Offscreen rendering (unless OnScreenRendering is 1)
239  // and re-render them, the backbuffer of the render widget is taken as-is
240  // (this is useful for lower quality screenshot or thumbnails).
241  // Return 1 on success, 0 otherwise
242  // GetRenderWidget() need to be implemented accordingly.
243  virtual int AppendAllWidgetsToImageData(vtkImageData *image,
244  int OnScreenRendering = 0);
245  virtual int AppendAllWidgetsToImageDataFast(vtkImageData *image);
246  virtual int AppendSelectedWidgetToImageData(vtkImageData *image);
247  virtual int AppendSelectedWidgetToImageDataFast(vtkImageData *image);
248 
249  // Description:
250  // Use the alpha channel in screenshots (which will save a transparent
251  // image).
252  vtkBooleanMacro(UseAlphaChannelInScreenshot, int);
253  vtkGetMacro(UseAlphaChannelInScreenshot, int);
254  vtkSetMacro(UseAlphaChannelInScreenshot, int);
255 
256  // Description:
257  // Print all widgets or the selected one.
258  // If no DPI is provided, the DPI settings of the Window ivar is used.
259  // Return 1 on success, 0 otherwise
260  // GetRenderWidget() need to be implemented accordingly.
261  virtual int PrintAllWidgets();
262  virtual int PrintAllWidgetsAtResolution(double dpi);
263  virtual int PrintSelectedWidget();
264  virtual int PrintSelectedWidgetAtResolution(double dpi);
265 
266  // Description:
267  // Create a resolution entries menu (specifies its parent).
268  // Get the menu (so that it can be added as a cascade).
269  // Update the menu entries state, given the number of widgets.
270  // If the resolution is changed using a menu entry, a
271  // ResolutionChangedEvent event is sent.
272  virtual void CreateResolutionEntriesMenu(vtkKWMenu *parent);
273  vtkGetObjectMacro(ResolutionEntriesMenu, vtkKWMenu);
274  virtual void UpdateResolutionEntriesMenu();
275 
276  // Description:
277  // Create a resolution entries toolbar (specifies its parent).
278  // Get the toolbar.
279  // Update the menu entries state, given the number of widgets.
280  // If the resolution is changed using a toolbar button, a
281  // ResolutionChangedEvent event is sent.
282  virtual void CreateResolutionEntriesToolbar(vtkKWWidget *parent);
283  vtkGetObjectMacro(ResolutionEntriesToolbar, vtkKWToolbar);
284  virtual void UpdateResolutionEntriesToolbar();
285 
286  // Description:
287  // Events. The SelectionChangedEvent is triggered when the selection
288  // is changed. It is similar in concept as the 'SelectionChangedCommand'
289  // callbacks but can be used by multiple listeners/observers at a time.
290  //BTX
291  enum
292  {
293  SelectionChangedEvent = 10000,
294  ResolutionChangedEvent
295  };
296  //ETX
297 
298  // Description:
299  // The command is invoked when the user double-clicks on the layout frame,
300  // i.e. any region of the frame that is not occupied by one selection frame.
301  virtual void SetDoubleClickOnLayoutFrameCommand(
302  vtkObject *object, const char *method);
303 
304  // Description:
305  // Update the "enable" state of the object and its internal parts.
306  // Depending on different Ivars (this->Enabled, the application's
307  // Limited Edition Mode, etc.), the "enable" state of the object is updated
308  // and propagated to its internal parts/subwidgets. This will, for example,
309  // enable/disable parts of the widget UI, enable/disable the visibility
310  // of 3D widgets, etc.
311  virtual void UpdateEnableState();
312 
313  // Description:
314  // Update the selection lists
315  virtual void UpdateSelectionLists();
316 
317  // Description:
318  // Callbacks. Internal, do not use.
319  virtual void SelectWidgetCallback(vtkKWSelectionFrame*);
320  virtual void SelectAndMaximizeWidgetCallback(vtkKWSelectionFrame*);
321  virtual void CloseWidgetCallback(vtkKWSelectionFrame*);
322  virtual int ChangeWidgetTitleCallback(vtkKWSelectionFrame*);
323  virtual void WidgetTitleChangedCallback(vtkKWSelectionFrame*);
324  virtual void SwitchWidgetCallback(
325  const char *title, vtkKWSelectionFrame *widget);
326  virtual void ResolutionCallback(int i, int j);
327  virtual void NumberOfWidgetsHasChangedCallback();
328  virtual void DoubleClickOnLayoutFrameCallback();
329 
330  // Description:
331  // Pack all widgets. You shouldn't have to call this method, as it is called
332  // automatically each time the position of a widget is changed through
333  // SetWidgetPosition, or the resolution/origin is changed, or a widget
334  // is added. But sometimes you may want to trigger packing yourself if
335  // you need to set the positions of a lot of widgets simultaneously through
336  // SetImmediateWidgetPosition.
337  virtual void Pack();
338 
339  // Description:
340  // Set the widget position without repacking.
341  // Return 1 if the position was changed, 0 otherwise.
342  virtual int SetImmediateWidgetPosition(vtkKWSelectionFrame *w, int pos[2])
343  { return this->SetImmediateWidgetPosition(w, pos[0], pos[1]); }
344  virtual int SetImmediateWidgetPosition(
345  vtkKWSelectionFrame *w, int col, int row);
346 
347  // Description:
348  // Adjust the resolution so that all widgets are shown
349  virtual void AdjustResolution();
350 
351  // Description:
352  // Set resolution and origin at the same time, to minimize redraw
353  virtual void SetResolutionAndOrigin(int res[2], int origin[2])
354  { this->SetResolutionAndOrigin(res[0], res[1], origin[0], origin[1]); };
355  virtual void SetResolutionAndOrigin(
356  int nb_cols, int nb_rows, int col, int row);
357 
358 protected:
361 
362  // Description:
363  // Get if a specific position is inside the layout defined by the
364  // current resolution and origin.
365  virtual int IsPositionInLayout(int col, int row);
366  virtual int IsPositionInLayout(int pos[2])
367  { return this->IsPositionInLayout(pos[0], pos[1]); };
368 
369  // Description:
370  // Create the widget.
371  virtual void CreateWidget();
372 
373  int Resolution[2];
374  int MaximumResolution[2];
375  int Origin[2];
378 
381 
382  virtual void InvokeSelectionChangedCommand();
384 
386  virtual void InvokeDoubleClickOnLayoutFrameCommand();
387 
389 
390  // Description:
391  // Allocate a new widget.
392  virtual vtkKWSelectionFrame* AllocateWidget();
393 
394  // Description:
395  // Create a widget (i.e., create the underlying Tk widget) and configure it.
396  // If the layout manager has not been created, the widget won't be
397  // created either, since it is used as parent.
398  virtual void CreateWidget(vtkKWSelectionFrame*);
399  virtual void ConfigureWidget(vtkKWSelectionFrame*);
400 
401  // Description:
402  // Get the render widget (if any) associated to the selection
403  // frame at that point.
404  // Used to Print, Save/Copy screenshot, etc.
405  // This should be reimplemented by subclasses.
406  // This implementation searches for a vtkKWRenderWidget in the children
407  // of the frame.
408  virtual vtkKWRenderWidget* GetRenderWidget(vtkKWSelectionFrame*);
409 
410  // Description:
411  // Print widgets (if selection_only is true, only the selected
412  // widget is printed, otherwise all of them).
413  // Return 1 on success, 0 otherwise
414  virtual int PrintWidgets(double dpi, int selection_only);
415 
416  // Description:
417  // Append dataset widgets to image data.
418  // If selection_only is true, onlythe selected dataset widget is printed,
419  // otherwise all of them. If direct is true, the renderwidgets are not
420  // set to Offscreen rendering and re-rendered, the backbuffer of the
421  // window is taken as-is (this is useful for lower quality screenshot or
422  // thumbnails).
423  // If direct is true and ForceUpdateOnScreenRendering is 1, the render
424  // widgets are forcibly re-rendererd prior to grabbing the screenshot.
425  // Return 1 on success, 0 otherwise
426  virtual int AppendWidgetsToImageData(
427  vtkImageData *image,int selection_only, int direct = 0,
428  int ForceUpdateOnScreenRendering = 0);
429 
430  // Description:
431  // Called when the number of widgets has changed
432  virtual void NumberOfWidgetsHasChanged();
433  virtual void ScheduleNumberOfWidgetsHasChanged();
434 
435  // Description:
436  // Reorganize positions of widgets so that the grid defined
437  // by the current resolution is filled.
438  // Return the number of reorganized widgets (number of widgets which
439  // position was changed).
440  virtual int ReorganizeWidgetPositions();
441 
442  // Description:
443  // Can a given widget's title be changed to a new one
444  // It is used by ChangeWidgetTitleCallback and is likely to be overriden
445  // in subclasses.
446  virtual int CanWidgetTitleBeChanged(
447  vtkKWSelectionFrame *widget, const char *new_title);
448 
449  // PIMPL Encapsulation for STL containers
450 
451  vtkKWSelectionFrameLayoutManagerInternals *Internals;
452 
453  // Description:
454  // Add/Remove callbacks on a selection frame
455  virtual void AddCallbacksToWidget(vtkKWSelectionFrame *widget);
456  virtual void RemoveCallbacksFromWidget(vtkKWSelectionFrame *widget);
457 
458  // Description:
459  // Delete a widget, i.e. Close and UnRegister it. Internal use only, as
460  // a helper to the public RemoveWidget methods.
461  virtual void DeleteWidget(vtkKWSelectionFrame *widget);
462 
463  // Description:
464  // Automatically move the selection inside the visible layout, i.e. if
465  // the selected widget is not visible, select a visible one.
466  // If pos_hint is non-null, use it as a hint regarding where the most
467  // likely selection could be (array of 2 ints).
468  virtual void MoveSelectionInsideVisibleLayout(int *pos_hint);
469 
470  // Description:
471  // Push/Pop resolutions or origins on a stack
472  // Is used by the maximize/minimize code.
473  virtual int PushResolution(int nb_cols, int nb_rows);
474  virtual int PushResolution(int res[2])
475  { return this->PushResolution(res[0], res[1]); };
476  virtual int PopResolution(int *nb_cols, int *nb_rows);
477  virtual int PopResolution(int res[2])
478  { return this->PopResolution(&res[0], &res[1]); };
479  virtual int PushPosition(int col, int row);
480  virtual int PushPosition(int origin[2])
481  { return this->PushPosition(origin[0], origin[1]); };
482  virtual int PopPosition(int *col, int *row);
483  virtual int PopPosition(int origin[2])
484  { return this->PopPosition(&origin[0], &origin[1]); };
485 
486  // Description:
487  // Save/Restore layout before maximize/minimize.
488  // Return 1 on success, 0 otherwise
489  virtual int SaveLayoutBeforeMaximize();
490  virtual int RestoreLayoutBeforeMaximize();
491 
492 private:
493 
495  void operator=(const vtkKWSelectionFrameLayoutManager&); // Not implemented
496 };
497 
498 #endif