KWWidgets
vtkKWPresetSelector.h
Go to the documentation of this file.
1 /*=========================================================================
2 
3  Module: $RCSfile: vtkKWPresetSelector.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 vtkKWPresetSelector - a preset selector.
15 // .SECTION Description
16 // This class is the basis for a preset selector framework.
17 // Presets can be added to the selector and identified by unique IDs.
18 // They can be assigned pre-defined fields like a group, a filename,
19 // a comment, a thumbnail and a screenshot, as well as an unlimited number
20 // of user-defined slots.
21 // Presets are listed vertically in a table list widget (vtkKWMultiColumnList),
22 // one by row. Each column is used to display one of the predefined field.
23 // The class can be used as-is, or extended to support more columns or
24 // features, as examplified in the vtkKWWindowLevelPresetSelector and
25 // vtkKWVolumePropertyPresetSelector sub-classes.
26 // Several callbacks can be specified to enable external code to
27 // add presets, apply presets, update them, etc.
28 // presets.
29 // .SECTION Thanks
30 // This work is part of the National Alliance for Medical Image
31 // Computing (NAMIC), funded by the National Institutes of Health
32 // through the NIH Roadmap for Medical Research, Grant U54 EB005149.
33 // Information on the National Centers for Biomedical Computing
34 // can be obtained from http://nihroadmap.nih.gov/bioinformatics.
35 // .SECTION See Also
36 // vtkKWWindowLevelPresetSelector vtkKWVolumePropertyPresetSelector
37 
38 #ifndef __vtkKWPresetSelector_h
39 #define __vtkKWPresetSelector_h
40 
41 #include "vtkKWCompositeWidget.h"
42 
43 class vtkImageData;
44 class vtkKWIcon;
46 class vtkKWPresetSelectorInternals;
47 class vtkKWPushButtonSet;
48 class vtkRenderWindow;
49 class vtkKWMenu;
50 class vtkKWToolbar;
52 
54 {
55 public:
56  static vtkKWPresetSelector* New();
57  vtkTypeRevisionMacro(vtkKWPresetSelector, vtkKWCompositeWidget);
58  void PrintSelf(ostream& os, vtkIndent indent);
59 
60  // Description:
61  // Add a new preset to the end of the list, or insert a preset in front
62  // of another preset, given its Id (if passed -1 as Id, insert at the
63  // beginning).
64  // Return the unique Id of the new preset, or -1 on error.
65  virtual int AddPreset();
66  virtual int InsertPreset(int id);
67 
68  // Description:
69  // Query if pool has given preset.
70  // Return 1 if in the pool, 0 otherwise
71  virtual int HasPreset(int id);
72 
73  // Description:
74  // Set/Get the group associated to a preset.
75  // This provide a way of grouping presets.
76  // The group field is not displayed as a column by default, but this
77  // can be changed using the SetGroupColumnVisibility() method.
78  // This column can not be edited by default, but this can be changed by
79  // a subclass.
80  // Return 1 on success, 0 on error
81  virtual int SetPresetGroup(int id, const char *group);
82  virtual const char* GetPresetGroup(int id);
83 
84  // Description:
85  // Set/Get the visibility of the group column. Hidden by default.
86  // No effect if called before Create().
87  virtual void SetGroupColumnVisibility(int);
88  virtual int GetGroupColumnVisibility();
89  vtkBooleanMacro(GroupColumnVisibility, int);
90 
91  // Description:
92  // Set/Get the title of the group column.
93  // No effect if called before Create().
94  virtual void SetGroupColumnTitle(const char *);
95  virtual const char* GetGroupColumnTitle();
96 
97  // Description:
98  // Set/Get the comment associated to a preset.
99  // This provide a way to create a small description or comment for
100  // each preset.
101  // The comment field is displayed as a column by default, but this
102  // can be changed using the SetCommentColumnVisibility() method.
103  // This column can be edited by default, by double-clicking
104  // on the corresponding table cell.
105  // Return 1 on success, 0 on error
106  virtual int SetPresetComment(int id, const char *comment);
107  virtual const char* GetPresetComment(int id);
108 
109  // Description:
110  // Set/Get the visibility of the comment column.
111  // No effect if called before Create().
112  virtual void SetCommentColumnVisibility(int);
113  virtual int GetCommentColumnVisibility();
114  vtkBooleanMacro(CommentColumnVisibility, int);
115 
116  // Description:
117  // Set/Get the filename associated to a preset.
118  // This field is neither used nor displayed in this implementation
119  // but is provided for subclasses that need to save preset to disks
120  // and keep track of the corresponding filename.
121  // A method is available to retrieve the Id of the preset that has
122  // been assigned a specific filename (if passed a relative name, compare
123  // the filenames without their paths).
124  // Return 1 on success, 0 on error (id on success, -1 otherwise)
125  virtual int SetPresetFileName(int id, const char *filename);
126  virtual const char* GetPresetFileName(int id);
127  virtual int GetIdOfPresetWithFileName(const char *filename);
128 
129  // Description:
130  // Get the creation time of a preset, as returned by
131  // the vtksys::SystemTools::GetTime() method, but in milliseconds.
132  // This field is not displayed in this implementation, but is
133  // used internally in the thumbnail column so that sorting by
134  // "thumbnail" will actually sort by creation time.
135  // Return 0 on error.
136  virtual vtkTypeInt64 GetPresetCreationTime(int id);
137 
138  // Description:
139  // Set/Get the thumbnail and screenshot associated to a preset.
140  // The thumbnail is displayed in the thumbnail column, and the screenshot
141  // is displayed as a pop-up when the user hovers over that thumbnail.
142  // The thumbnail field is not displayed as a column by default, but this
143  // can be changed using the SetThumbnailColumnVisibility() method.
144  // Note that the vtkKWIcon object passed as parameter is neither
145  // stored nor Register()'ed, only a copy is stored (and updated each
146  // time the Set... method is called later on).
147  virtual vtkKWIcon* GetPresetThumbnail(int id);
148  virtual int SetPresetThumbnail(int id, vtkKWIcon *icon);
149  virtual vtkKWIcon* GetPresetScreenshot(int id);
150  virtual int SetPresetScreenshot(int id, vtkKWIcon *icon);
151 
152  // Description:
153  // Set/Get the visibility of the thumbnail column.
154  // No effect if called before Create().
155  virtual void SetThumbnailColumnVisibility(int);
156  virtual int GetThumbnailColumnVisibility();
157  vtkBooleanMacro(ThumbnailColumnVisibility, int);
158 
159  // Description:
160  // Build both the thumbnail and screenshot for a specific preset using a
161  // vtkImageData. The thumbnail is constructed by resampling the image to
162  // fit the ThumbnailSize constraint. The screenshot is constructed by
163  // resampling the image to fit the ScreenshotSize constraint.
164  // This method is typically useful to build both thumbnail
165  // and screenshot from a single larger image (or screenshot).
166  // A similar method can be passed a vtkRenderWindow instead of a
167  // vtkImageData; in that case, the window contents is grabbed and used
168  // to build both thumbnail and screenshot.
169  // Both thumbnail and screenshot icons can be retrieved.
170  // Return 1 on success, 0 on error
171  virtual int BuildPresetThumbnailAndScreenshotFromImage(
172  int id, vtkImageData *image);
173  virtual int BuildPresetThumbnailAndScreenshotFromRenderWindow(
174  int id, vtkRenderWindow *win);
175 
176  // Description:
177  // Flip the thumbnail and screenshot vertically for a specific preset
178  // Return 1 on success, 0 on error
179  virtual int FlipPresetThumbnailAndScreenshotVertically(int id);
180 
181  // Description:
182  // Set/Get the thumbnail size.
183  // Changing the size will not resize the current thumbnails, but will
184  // affect the presets added to the selector later on using the
185  // BuildPresetThumbnailAndScreenshotFromImage method.
186  vtkSetClampMacro(ThumbnailSize,int,8,512);
187  vtkGetMacro(ThumbnailSize,int);
188 
189  // Description:
190  // Set/Get the screenshot size, i.e. the image that appears as
191  // a popup when the mouse is on top of the thumbnail.
192  // Changing the size will not resize the current screenshots, but will
193  // affect the presets added to the selector later on using the
194  // BuildPresetThumbnailAndScreenshotFromImage method.
195  vtkSetClampMacro(ScreenshotSize,int,8,2048);
196  vtkGetMacro(ScreenshotSize,int);
197 
198  // Description:
199  // Set/Get a preset user slot.
200  // An unlimited number of slots can be added to a preset. Each slot is
201  // identified by a name (string). Methods are provided to store
202  // and retrieve various types of data (double, int, string, generic pointer,
203  // pointer to vtkObject). Note a SetPresetUserSlotAsObject *does* call
204  // Register() on the object passed as parameter, and will call UnRegister()
205  // once it is time to remove/deallocate all presets (either automatically
206  // when this instance is deleted or programatically).
207  // Note that setting the value of a slot will automatically call
208  // ScheduleUpdatePresetRow for the specific preset if the value was
209  // different than the previous value.
210  // Return 1 on success, 0 on error
211  //BTX
212  enum
213  {
214  UserSlotDoubleType = 0,
215  UserSlotIntType,
216  UserSlotUnsignedLongType,
217  UserSlotInt64Type,
218  UserSlotStringType,
219  UserSlotPointerType,
220  UserSlotObjectType,
221  UserSlotUnknownType
222  };
223  //ETX
224  virtual int HasPresetUserSlot(
225  int id, const char *slot_name);
226  virtual int GetPresetUserSlotType(
227  int id, const char *slot_name);
228  virtual int DeletePresetUserSlot(
229  int id, const char *slot_name);
230  virtual int SetPresetUserSlotAsDouble(
231  int id, const char *slot_name, double value);
232  virtual double GetPresetUserSlotAsDouble(
233  int id, const char *slot_name);
234  virtual int SetPresetUserSlotAsInt(
235  int id, const char *slot_name, int value);
236  virtual int GetPresetUserSlotAsInt(
237  int id, const char *slot_name);
238  virtual int SetPresetUserSlotAsUnsignedLong(
239  int id, const char *slot_name, unsigned long value);
240  virtual unsigned long GetPresetUserSlotAsUnsignedLong(
241  int id, const char *slot_name);
242  virtual int SetPresetUserSlotAsInt64(
243  int id, const char *slot_name, vtkTypeInt64 value);
244  virtual vtkTypeInt64 GetPresetUserSlotAsInt64(
245  int id, const char *slot_name);
246  virtual int SetPresetUserSlotAsString(
247  int id, const char *slot_name, const char *value);
248  virtual const char* GetPresetUserSlotAsString(
249  int id, const char *slot_name);
250  virtual int SetPresetUserSlotAsPointer(
251  int id, const char *slot_name, void *ptr);
252  virtual void* GetPresetUserSlotAsPointer(
253  int id, const char *slot_name);
254  virtual int SetPresetUserSlotAsObject(
255  int id, const char *slot_name, vtkObject *obj);
256  virtual vtkObject* GetPresetUserSlotAsObject(
257  int id, const char *slot_name);
258 
259  // Description:
260  // Most (if not all) of the information associated to a preset (say group,
261  // comment, filename, creation time, thumbnail and screenshot) is stored
262  // under the hood as user slots using the corresponding API (i.e.
263  // Set/GetPresetUserSlotAs...()). Since each slot requires a unique name,
264  // the following methods are provided to retrieve the slot name for
265  // the default preset fields. This can be useful to avoid collision between
266  // the default slots and your own user slots. Note that the default slot
267  // names can be changed too, but doing so will not transfer the value
268  // stored at the old slot name to the new slot name (it is up to you to do
269  // so, if needed).
270  virtual void SetPresetGroupSlotName(const char *);
271  virtual const char* GetPresetGroupSlotName();
272  virtual void SetPresetCommentSlotName(const char *);
273  virtual const char* GetPresetCommentSlotName();
274  virtual void SetPresetFileNameSlotName(const char *);
275  virtual const char* GetPresetFileNameSlotName();
276  virtual void SetPresetCreationTimeSlotName(const char *);
277  virtual const char* GetPresetCreationTimeSlotName();
278  virtual void SetPresetThumbnailSlotName(const char *);
279  virtual const char* GetPresetThumbnailSlotName();
280  virtual void SetPresetScreenshotSlotName(const char *);
281  virtual const char* GetPresetScreenshotSlotName();
282 
283  // Description:
284  // Set/Get the preset filter constraints.
285  // The preset filter is a set of constraints that a preset has to match
286  // to be visible in the preset list.
287  // Only string and int slots are supported at the moment.
288  // At the moment, constraints are expressed as string values (default) or
289  // regular expressions that have to match specific user slots. An
290  // unlimited number of constraints can be added.
291  // For example, if 'slot_name' is 'Modality', and 'value' is
292  // 'CT', then only those presets which have a 'Modality' user slot with
293  // a string value of 'CT' will be displayed.
294  // Note that the constraint type can be changed from regular expression
295  // to plain character-for-character string comparison using either
296  // SetPresetFilterUserSlotConstraintToRegularExpression or
297  // SetPresetFilterUserSlotConstraintToString; however the constraint needs to
298  // exist for that slot name for this change to be made. When one constraint
299  // is added, its default type is String, not RegularExpression.
300  // Use a NULL value for to remove the constraint on a specific slot or
301  // call DeletePresetFilterUserSlotConstraint
302  virtual void ClearPresetFilter();
303  virtual void SetPresetFilterUserSlotConstraint(
304  const char *slot_name, const char *value);
305  virtual const char* GetPresetFilterUserSlotConstraint(
306  const char *slot_name);
307  virtual void DeletePresetFilterUserSlotConstraint(const char *slot_name);
308  virtual void SetPresetFilterUserSlotConstraintToRegularExpression(
309  const char *slot_name);
310  virtual void SetPresetFilterUserSlotConstraintToString(
311  const char *slot_name);
312 
313  // Description:
314  // Add a preset filter constraint on the preset group field.
315  virtual void SetPresetFilterGroupConstraint(const char *value);
316  virtual const char* GetPresetFilterGroupConstraint();
317 
318  // Description:
319  // Query if a given preset matches the current preset filter constraints.
320  // Return 1 if match or if no filter was defined, 0 otherwise
321  virtual int IsPresetFiltered(int id);
322 
323  // Description:
324  // Get the number of presets, or the number of presets with a specific
325  // group, or the number of visible presets, i.e. the presets that are
326  // displayed according to the preset filters for example.
327  virtual int GetNumberOfPresets();
328  virtual int GetNumberOfPresetsWithGroup(const char *group);
329  virtual int GetNumberOfVisiblePresets();
330 
331  // Description:
332  // Set/Get the maximum number of presets. When this number is passed, the
333  // oldest preset (according to the PresetCreationTime) is deleted
334  // automatically. Set it to 0 (default) to allow for unlimited number
335  // of presets.
336  vtkGetMacro(MaximumNumberOfPresets, int);
337  virtual void SetMaximumNumberOfPresets(int);
338 
339  // Description:
340  // Query if a given preset is visible (i.e. displayed in the list).
341  // Some presets can be hidden, for example if they do not match
342  // the current preset filter constraints.
343  virtual int GetPresetVisibility(int id);
344 
345  // Description:
346  // Retrieve the Id of the nth-preset, or the id of the
347  // nth preset with a given group.
348  // Return id on success, -1 otherwise
349  virtual int GetIdOfNthPreset(int index);
350  virtual int GetIdOfNthPresetWithGroup(int index, const char *group);
351 
352  // Description:
353  // Retrieve the Id of the preset at a given row in the table, or
354  // the row of a given preset.
355  // Return id or row index on success, -1 otherwise
356  virtual int GetIdOfPresetAtRow(int row_index);
357  virtual int GetPresetRow(int id);
358 
359  // Description:
360  // Retrieve the rank of the nth preset with a given group
361  // (i.e. the nth-preset with a given group).
362  // This rank can then be used to retrieve the preset id using
363  // the GetIdOfNthPreset() method.
364  // Return rank on success, -1 otherwise
365  virtual int GetRankOfNthPresetWithGroup(int index, const char *group);
366 
367  // Description:
368  // Remove a preset, or all of them, or all of the presets
369  // with the same group.
370  // Return 1 on success, 0 on error
371  virtual int RemovePreset(int id);
372  virtual int RemoveAllPresets();
373  virtual int RemoveAllPresetsWithGroup(const char *group);
374 
375  // Description:
376  // Select a preset, clear the selection.
377  virtual void SelectPreset(int id);
378  virtual void SelectPreviousPreset();
379  virtual void SelectNextPreset();
380  virtual void ClearSelection();
381  virtual int GetIdOfSelectedPreset();
382 
383  // Description:
384  // Set/Get the list height (in number of items) or width (in chars)
385  // No effect if called before Create().
386  virtual void SetListHeight(int);
387  virtual int GetListHeight();
388  virtual void SetListWidth(int);
389  virtual int GetListWidth();
390 
391  // Description:
392  // Set/Get the base icons to use for the preset buttons (and the toolbar).
393  // The base icon has to be in RGBA format, and will be composited against
394  // a few different smaller icons to represent each action; for example,
395  // a '+' sign will be composited on top of the base icon for the
396  // "Add Preset" button.
397  vtkGetObjectMacro(PresetButtonsBaseIcon, vtkKWIcon);
398  virtual void SetPresetButtonsBaseIcon(vtkKWIcon *icon);
399  virtual void SetPresetButtonsBaseIconToPredefinedIcon(int icon_index);
400 
401  // Description:
402  // Set/Get the visibility of the select spin buttons.
403  // The select spin button are two buttons that can be used
404  // to select the next or previous preset in the list.
405  // Note that if ApplyPresetOnSelection is On, this will also apply
406  // the preset at the same time, thus providing a quick way to
407  // loop over all presets and apply them.
408  virtual void SetSelectSpinButtonsVisibility(int);
409  vtkGetMacro(SelectSpinButtonsVisibility,int);
410  vtkBooleanMacro(SelectSpinButtonsVisibility,int);
411 
412  // Description:
413  // Set/Get the visibility of the locate preset button and the "Locate" menu
414  // entry in the context menu (hidden by default).
415  // If visible, triggering this button will locate all selected presets
416  // by calling the GetPresetFileName method and trying to open
417  // the directory they are in and select the proper file.
418  // Win32 only at the moment.
419  virtual void SetLocateButtonVisibility(int);
420  vtkGetMacro(LocateButtonVisibility,int);
421  vtkBooleanMacro(LocateButtonVisibility,int);
422  vtkSetMacro(LocateMenuEntryVisibility,int);
423  vtkGetMacro(LocateMenuEntryVisibility,int);
424  vtkBooleanMacro(LocateMenuEntryVisibility,int);
425 
426  // Description:
427  // Set/Get the visibility of the email preset button and the "Email" menu
428  // entry in the context menu (hidden by default).
429  // If visible, triggering this button will email all selected presets
430  // as attachments. The attachment location is retrieved by calling
431  // the GetPresetFileName method. Win32/MAPI only at the moment.
432  virtual void SetEmailButtonVisibility(int);
433  vtkGetMacro(EmailButtonVisibility,int);
434  vtkBooleanMacro(EmailButtonVisibility,int);
435  vtkSetMacro(EmailMenuEntryVisibility,int);
436  vtkGetMacro(EmailMenuEntryVisibility,int);
437  vtkBooleanMacro(EmailMenuEntryVisibility,int);
438 
439  // Description:
440  // Set/Get the body of the email that will be sent alongside the attached
441  // preset when the "Email Preset" button or menu entry is triggered.
442  // Note that it will still appear after a shot paragraph describing which
443  // application sent that preset, the location of the preset on the sender's
444  // computer, the comment associated to the preset and its creation time.
445  vtkSetStringMacro(EmailBody);
446  vtkGetStringMacro(EmailBody);
447 
448  // Description:
449  // Set/Get the visibility of the remove preset button or the "Remove" entry
450  // in the context menu (visible by default).
451  // If visible, triggering this button will remove all selected presets and
452  // eventually call the callbacks that was set using SetPresetRemoveCommand.
453  virtual void SetRemoveButtonVisibility(int);
454  vtkGetMacro(RemoveButtonVisibility,int);
455  vtkBooleanMacro(RemoveButtonVisibility,int);
456  vtkGetMacro(RemoveMenuEntryVisibility,int);
457  vtkSetMacro(RemoveMenuEntryVisibility,int);
458  vtkBooleanMacro(RemoveMenuEntryVisibility,int);
459 
460  // Description:
461  // Set/Get the visibility of the filter button (hidden by default).
462  // If visible, clicking on this button will bring the a popup menu
463  // presenting all the unique values that were collected in the
464  // FilterButtonSlotName slot for all presets.
465  // Each one can be turn on and off, which will update the
466  // PresetFilterUserSlotConstraint automatically for that slot.
467  virtual void SetFilterButtonVisibility(int);
468  vtkGetMacro(FilterButtonVisibility,int);
469  vtkBooleanMacro(FilterButtonVisibility,int);
470  vtkSetStringMacro(FilterButtonSlotName);
471  vtkGetStringMacro(FilterButtonSlotName);
472 
473  // Description:
474  // Set/Get the visibility of the help message.
475  virtual void SetHelpLabelVisibility(int);
476  vtkGetMacro(HelpLabelVisibility,int);
477  vtkBooleanMacro(HelpLabelVisibility,int);
478  vtkGetObjectMacro(HelpLabel, vtkKWLabelWithLabel);
479  virtual void SetHelpLabelText(const char *);
480 
481  // Description:
482  // Specifies a command to associate with the widget. This command is
483  // typically invoked when the "add preset" button is pressed.
484  // This gives the opportunity for the application to check and collect the
485  // relevant information to store in a new preset. The application is then
486  // free to add the preset (using the AddPreset() method) and set its
487  // fields independently (using the SetPresetGroup(), SetPresetComment(),
488  // SetPreset...() methods).
489  // Note that if not set, the "add preset" button is not visible.
490  // The 'object' argument is the object that will have the method called on
491  // it. The 'method' argument is the name of the method to be called and any
492  // arguments in string form. If the object is NULL, the method is still
493  // evaluated as a simple command.
494  // The following output is expected from the command:
495  // - the unique id of the preset that was added (by calling AddPreset()),
496  // -1 otherwise
497  virtual void SetPresetAddCommand(vtkObject *object, const char *method);
498 
499  // Description:
500  // Specifies a command to associate with the widget. This command is
501  // typically invoked when the "update selected preset" button
502  // is pressed. This gives the opportunity for the application to check and
503  // collect the relevant information to update in the preset. The application
504  // is then free to update the preset's fields independently (using the
505  // SetPresetGroup(), SetPresetComment(), SetPreset...() methods).
506  // Note that if this command is not set, the corresponding
507  // "update selected preset" button is not visible.
508  // Note that if this command is not set, the corresponding "Update" entry
509  // is not shown in the context menu.
510  // The 'object' argument is the object that will have the method called on
511  // it. The 'method' argument is the name of the method to be called and any
512  // arguments in string form. If the object is NULL, the method is still
513  // evaluated as a simple command.
514  // The following parameters are also passed to the command:
515  // - the id of the preset to update: int
516  virtual void SetPresetUpdateCommand(vtkObject *object, const char *method);
517 
518  // Description:
519  // Specifies a command to associate with the widget. This command is
520  // typically invoked when the "apply selected preset" button is pressed,
521  // or when ApplyPresetOnSelection is On and the user
522  // applies a preset by selecting it directly. This gives the opportunity
523  // for the application to query the preset's fields independently (using the
524  // GetPresetGroup(), GetPresetComment(), GetPreset...() methods) and
525  // apply those values to the relevant objects.
526  // Note that if this command is not set or if ApplyPresetOnSelection is On,
527  // the corresponding "apply selected preset" button is not visible.
528  // Note that if this command is not set, the corresponding "Apply" entry
529  // is not shown in the context menu.
530  // The 'object' argument is the object that will have the method called on
531  // it. The 'method' argument is the name of the method to be called and any
532  // arguments in string form. If the object is NULL, the method is still
533  // evaluated as a simple command.
534  // The following parameters are also passed to the command:
535  // - the id of the preset to apply: int
536  virtual void SetPresetApplyCommand(vtkObject *object, const char *method);
537 
538  // Description:
539  // Set/Get if a preset should be applied directly when it is selected by a
540  // single-click, or only when the "apply selected preset" button is pressed.
541  // If set, only one preset can be selected at a time (if not, multiple
542  // preset can be selected, and removed for example).
543  // Note that if set, the "apply selected preset" button is not visible.
544  virtual void SetApplyPresetOnSelection(int);
545  vtkGetMacro(ApplyPresetOnSelection,int);
546  vtkBooleanMacro(ApplyPresetOnSelection,int);
547 
548  // Description:
549  // Specifies a command to associate with the widget. This command is
550  // typically invoked when the "remove selected preset"
551  // button is pressed. This command is called *before* the preset is
552  // removed from the pool: this gives the opportunity for the application
553  // to query the preset's fields independently (using the
554  // GetPresetGroup(), GetPresetComment(), GetPreset...() methods),
555  // decide if the preset should be removed or not, and delete it from
556  // its internal structures accordingly, if needed.
557  // The 'object' argument is the object that will have the method called on
558  // it. The 'method' argument is the name of the method to be called and any
559  // arguments in string form. If the object is NULL, the method is still
560  // evaluated as a simple command.
561  // The following parameters are also passed to the command:
562  // - the id of the preset to remove: int
563  // The following output is expected from the command:
564  // - whereas the preset is really to be removed (1) or not (0): int
565  virtual void SetPresetRemoveCommand(vtkObject *object, const char *method);
566 
567  // Description:
568  // Specifies a command to associate with the widget. This command is
569  // typically invoked when a preset has been removed as a result of
570  // pressing the "remove selected preset" button. As opposed to the
571  // PresetRemoveCommand, this command is called *after* the preset is
572  // removed from the pool and only if it has been removed (its Id is
573  // therefore not passed to the callback as a parameter). Do not confuse
574  // this command with PresetRemoveCommand which gives the opportunity for
575  // the application to decide if the preset should be removed or not.
576  // The 'object' argument is the object that will have the method called on
577  // it. The 'method' argument is the name of the method to be called and any
578  // arguments in string form. If the object is NULL, the method is still
579  // evaluated as a simple command.
580  virtual void SetPresetRemovedCommand(vtkObject *object, const char *method);
581 
582  // Description:
583  // Set/Get if the user should be prompted before removing one or
584  // more presets using "remove selected preset" button.
585  vtkSetMacro(PromptBeforeRemovePreset, int);
586  vtkGetMacro(PromptBeforeRemovePreset, int);
587  vtkBooleanMacro(PromptBeforeRemovePreset, int);
588 
589  // Description:
590  // Specifies a command to associate with the widget. This command is
591  // typically invoked when the preset has been changed using direct
592  // user-interaction on the widget interface.
593  // This includes double-clicking on a table cell (the comment field for
594  // example) and editing the contents of the cell directly, when allowed.
595  // This gives the opportunity for the application to query the preset's
596  // fields independently (using the GetPresetGroup(), GetPresetComment(),
597  // GetPreset...() methods), and update its internal structures accordingly,
598  // if needed.
599  // The 'object' argument is the object that will have the method called on
600  // it. The 'method' argument is the name of the method to be called and any
601  // arguments in string form. If the object is NULL, the method is still
602  // evaluated as a simple command.
603  // The following parameters are also passed to the command:
604  // - the id of the preset that has changed: int
605  virtual void SetPresetHasChangedCommand(
606  vtkObject *object, const char *method);
607 
608  // Description:
609  // Specifies a command to associate with the widget. This command is
610  // typically invoked when the "load preset" button is pressed.
611  // This gives the opportunity for the application to invoke a file dialog,
612  // let the user pick a preset file, load it and collect the relevant
613  // information to store in a new preset. The application is then
614  // free to add the preset (using the AddPreset() method) and set its
615  // fields independently (using the SetPresetGroup(), SetPresetComment(),
616  // SetPreset...() methods).
617  // Note that if not set, the "load preset" button is not visible.
618  // The 'object' argument is the object that will have the method called on
619  // it. The 'method' argument is the name of the method to be called and any
620  // arguments in string form. If the object is NULL, the method is still
621  // evaluated as a simple command.
622  // The following output is expected from the command:
623  // - the unique id of the preset that was loaded and added (by calling
624  // AddPreset()), -1 otherwise
625  virtual void SetPresetLoadCommand(vtkObject *object, const char *method);
626 
627  // Description:
628  // Specifies a command to associate with the widget. This command is
629  // typically invoked when the preset filtering has changed, i.e. a filter
630  // constraint has been added/removed (see, ClearPresetFilter or
631  // SetPresetFilterUserSlotConstraint).
632  // The 'object' argument is the object that will have the method called on
633  // it. The 'method' argument is the name of the method to be called and any
634  // arguments in string form. If the object is NULL, the method is still
635  // evaluated as a simple command.
636  virtual void SetPresetFilteringHasChangedCommand(
637  vtkObject *object, const char *method);
638 
639  // Description:
640  // Refresh the interface.
641  virtual void Update();
642 
643  // Description:
644  // Update the "enable" state of the object and its internal parts.
645  // Depending on different Ivars (this->Enabled, the application's
646  // Limited Edition Mode, etc.), the "enable" state of the object is updated
647  // and propagated to its internal parts/subwidgets. This will, for example,
648  // enable/disable parts of the widget UI, enable/disable the visibility
649  // of 3D widgets, etc.
650  virtual void UpdateEnableState();
651 
652  // Description:
653  // Callback used to refresh the contents of the image cell for each preset
654  virtual void PresetCellThumbnailCallback(const char*, int, int, const char*);
655 
656  // Description:
657  // Callback invoked when the user starts editing a specific preset field
658  // located at cell ('row', 'col'), which current contents is 'text'.
659  // This method returns the value that is to become the initial
660  // contents of the temporary embedded widget used for editing: most of the
661  // time, this is the same value as 'text'.
662  // The next step (validation) is handled by PresetCellEditEndCallback
663  virtual const char* PresetCellEditStartCallback(
664  int row, int col, const char *text);
665 
666  // Description:
667  // Callback invoked when the user ends editing a specific preset field
668  // located at cell ('row', 'col').
669  // The main purpose of this method is to perform a final validation of
670  // the edit window's contents 'text'.
671  // This method returns the value that is to become the new contents
672  // for that cell.
673  // The next step (updating) is handled by PresetCellUpdateCallback
674  virtual const char* PresetCellEditEndCallback(
675  int row, int col, const char *text);
676 
677  // Description:
678  // Callback invoked when the user successfully updated the preset field
679  // located at ('row', 'col') with the new contents 'text', as a result
680  // of editing the corresponding cell interactively.
681  virtual void PresetCellUpdatedCallback(int row, int col, const char *text);
682 
683  // Description:
684  // Retrieve the toolbar. Use that method to set the parent of this object to
685  // a specific widget or toolbar set (vtkKWToolbarSet), before calling
686  // CreateToolbar.
687  virtual vtkKWToolbar* GetToolbar();
688 
689  // Description:
690  // Create the toolbar. If the toolbar has to be placed in a specific location
691  // in the application, call the GetToolbar method and set the toolbar parent
692  // beforehand.
693  virtual void CreateToolbar();
694 
695  // Description:
696  // Some constants
697  //BTX
698  static const char *IdColumnName;
699  static const char *ThumbnailColumnName;
700  static const char *GroupColumnName;
701  static const char *CommentColumnName;
702  //ETX
703 
704  // Description:
705  // Callbacks. Internal, do not use.
706  virtual int PresetAddCallback();
707  virtual void PresetApplyCallback();
708  virtual void PresetApplyCallback(int id);
709  virtual void PresetUpdateCallback();
710  virtual void PresetUpdateCallback(int id);
711  virtual void PresetRemoveCallback();
712  virtual void PresetRemoveAllCallback();
713  virtual void PresetRemoveCallback(int id);
714  virtual void PresetEmailCallback();
715  virtual void PresetEmailCallback(int id);
716  virtual void PresetLocateCallback();
717  virtual void PresetLocateCallback(int id);
718  virtual void PresetSelectionCallback();
719  virtual void PresetSelectionChangedCallback();
720  virtual void PresetRightClickCallback(int row, int col, int x, int y);
721  virtual int PresetLoadCallback();
722  virtual void PresetFilterCallback();
723  virtual void PresetFilterApplyCallback(const char *regexp);
724  virtual void UpdatePresetRowCallback(int id);
725  virtual void UpdatePresetRowsCallback();
726  virtual void ColumnSortedCallback();
727  virtual void RowMovedCallback();
728  virtual void SchedulePresetSelectionCallback();
729  virtual void SchedulePresetSelectionChangedCallback();
730 
731  // Description:
732  // Access to the internal multicolumn list.
733  // This is temporary, this internal widget may change.
734  vtkGetObjectMacro(PresetList, vtkKWMultiColumnListWithScrollbars);
735 
736  // Description:
737  // Set the callbacks to be used to create, update, and set the icons and
738  // help strings on user-defined buttons. These callbacks can be used to
739  // add buttons to the preset selector toolbar(s), without subclassing it.
740  // The 'object' argument is the object that will have the method called on
741  // it. The 'method' argument is the name of the method to be called and any
742  // arguments in string form. If the object is NULL, the method is still
743  // evaluated as a simple command.
744  // Note that each callback will receive the following parameters:
745  // CreateUserPresetButtonsCommand: vtkKWToolbar *toolbar, int use_separators
746  // UpdateUserPresetButtonsCommand: vtkKWToolbar *toolbar
747  // SetUserPresetButtonsIconsCommand: vtkKWToolbar *toolbar
748  // SetUserPresetButtonsHelpStringsCommand: vtkKWToolbar *toolbar
749  virtual void SetCreateUserPresetButtonsCommand(
750  vtkObject *object, const char *method);
751  virtual void SetUpdateUserPresetButtonsCommand(
752  vtkObject *object, const char *method);
753  virtual void SetSetUserPresetButtonsIconsCommand(
754  vtkObject *object, const char *method);
755  virtual void SetSetUserPresetButtonsHelpStringsCommand(
756  vtkObject *object, const char *method);
757 
758 protected:
761 
762  // Description:
763  // Create the widget.
764  virtual void CreateWidget();
765 
766  // Description:
767  // Create the columns.
768  // Subclasses should override this method to add their own columns and
769  // display their own preset fields (do not forget to call the superclass
770  // first).
771  virtual void CreateColumns();
772 
773  // Description:
774  // Create the preset buttons in the toolbar.
775  // Subclasses should override this method to add their own toolbar buttons
776  // (do not forget to call the superclass first).
777  virtual void CreateToolbarPresetButtons(vtkKWToolbar*, int use_separators);
778 
779  // Description:
780  // Update the toolbar preset buttons state/visibility.
781  virtual void UpdateToolbarPresetButtons(vtkKWToolbar*);
782 
783  // Description:
784  // Set the toolbar preset buttons icons.
785  // Subclasses should override this method to set their own icons
786  // (do not forget to call the superclass first).
787  virtual void SetToolbarPresetButtonsIcons(vtkKWToolbar*);
788 
789  // Description:
790  // Set the toolbar preset buttons balloon help strings
791  // Subclass can override this method to change the help strings
792  // associated to the buttons.
793  virtual void SetToolbarPresetButtonsHelpStrings(vtkKWToolbar*);
794 
795  // Description:
796  // Configure a new preset.
797  // Subclasses should override this method to configure a newly allocated
798  // preset, i.e. assign its internal values (do not forget to call the
799  // superclass first).
800  virtual void ConfigureNewPreset(int id);
801 
802  // Description:
803  // Deallocate a preset.
804  // Subclasses should override this method to release the memory allocated
805  // by their own preset fields (do not forget to call the superclass
806  // first).
807  virtual void DeAllocatePreset(int id);
808 
809  // Description:
810  // Update the preset row, i.e. add a row for that preset if it is not
811  // displayed already, hide it if it does not match the filters, and
812  // update the table columns with the corresponding preset fields.
813  // Subclass should override this method to display their own fields.
814  // Return 1 on success, 0 if the row was not (or can not be) updated.
815  // Subclasses should call the parent's UpdatePresetRow, and abort
816  // if the result is not 1.
817  virtual int UpdatePresetRow(int id);
818  virtual void ScheduleUpdatePresetRow(int id);
819 
820  // Description:
821  // Update the preset row itself in the list, i.e. add or remove a row
822  // for a specific preset id in the multicolumn list. UpdatePresetRow() and/or
823  // ScheduleUpdatePresetRow() will call this function first, then add
824  // the contents of the row itself. Pass/set is_new to 1 if you are
825  // sure the preset is new and was never inserted in the list.
826  // Return row index on success (can be 0), -1 otherwise.
827  virtual int UpdatePresetRowInMultiColumnList(int id, int is_new = 0);
828 
830  vtkKWFrame *PresetControlFrame;
831  vtkKWToolbar *PresetButtons;
832  vtkKWToolbar *Toolbar;
833  vtkKWLabelWithLabel *HelpLabel;
834  vtkKWMenu *ContextMenu;
835  vtkKWIcon *PresetButtonsBaseIcon;
836 
837 
838  int ApplyPresetOnSelection;
839  int SelectSpinButtonsVisibility;
840  int EmailButtonVisibility;
841  int EmailMenuEntryVisibility;
842  int LocateButtonVisibility;
843  int LocateMenuEntryVisibility;
844  int RemoveButtonVisibility;
845  int RemoveMenuEntryVisibility;
846  int HelpLabelVisibility;
847  int FilterButtonVisibility;
848 
849  int ThumbnailSize;
850  int ScreenshotSize;
851  int PromptBeforeRemovePreset;
852  int MaximumNumberOfPresets;
853 
854  char *EmailBody;
855  char *FilterButtonSlotName;
856 
857  // Description:
858  // Called when the number of presets has changed.
859  // Note that the name of this function can be a bit misleading: if
860  // MaximumNumberOfPresets is set to a positive number, and the max
861  // has been reached, this function will *still* be called twice, once
862  // when the max is passed as a result of adding a preset, and then another
863  // time when a preset is automatically deleted to get back to the maximum
864  // value (which is, in most case, what you want to know anyway).
865  virtual void NumberOfPresetsHasChanged();
866 
867  // Description:
868  // Called when preset filtering has changed, i.e. a filter
869  // constraint has been added/removed (see, ClearPresetFilter or
870  // SetPresetFilterUserSlotConstraint).
871  virtual void PresetFilteringHasChanged();
872 
873  // Description:
874  // Called when preset filtering *may* have changed, the value of a slot has
875  // changed and that slot was filtered (i.e. had a constraint put on it
876  // using SetPresetFilterUserSlotConstraint), therefore it is possible that
877  // preset maybe pass or not pass the filter anymore (IsPresetFiltered).
878  virtual void PresetFilteringMayHaveChanged();
879 
880  // PIMPL Encapsulation for STL containers
881  //BTX
882  vtkKWPresetSelectorInternals *Internals;
883  //ETX
884 
885  // Description:
886  // Update all rows in the list
887  virtual void UpdatePresetRows();
888  virtual void ScheduleUpdatePresetRows();
889  virtual void CancelScheduleUpdatePresetRows();
890 
891  char *PresetAddCommand;
892  virtual int InvokePresetAddCommand();
893 
894  char *PresetUpdateCommand;
895  virtual void InvokePresetUpdateCommand(int id);
896 
897  char *PresetApplyCommand;
898  virtual void InvokePresetApplyCommand(int id);
899 
900  char *PresetRemoveCommand;
901  virtual int InvokePresetRemoveCommand(int id);
902 
903  char *PresetRemovedCommand;
904  virtual void InvokePresetRemovedCommand();
905 
906  char *PresetHasChangedCommand;
907  virtual void InvokePresetHasChangedCommand(int id);
908 
909  char *PresetLoadCommand;
910  virtual int InvokePresetLoadCommand();
911 
912  char *PresetFilteringHasChangedCommand;
913  virtual void InvokePresetFilteringHasChangedCommand();
914 
915  char *CreateUserPresetButtonsCommand;
916  virtual void InvokeCreateUserPresetButtonsCommand(vtkKWToolbar *, int);
917 
918  char *UpdateUserPresetButtonsCommand;
919  virtual void InvokeUpdateUserPresetButtonsCommand(vtkKWToolbar *);
920 
921  char *SetUserPresetButtonsIconsCommand;
922  virtual void InvokeSetUserPresetButtonsIconsCommand(vtkKWToolbar *);
923 
924  char *SetUserPresetButtonsHelpStringsCommand;
925  virtual void InvokeSetUserPresetButtonsHelpStringsCommand(vtkKWToolbar *);
926 
927  // Description:
928  // Get the index of a given column.
929  virtual int GetIdColumnIndex();
930  virtual int GetThumbnailColumnIndex();
931  virtual int GetGroupColumnIndex();
932  virtual int GetCommentColumnIndex();
933 
934  // Description:
935  // Pack
936  virtual void Pack();
937 
938  // Description:
939  // Populate the pop-up context menu that is displayed when right-clicking
940  // on a give preset. It should replicate the commands available through the
941  // preset buttons.
942  virtual void PopulatePresetContextMenu(vtkKWMenu *menu, int id);
943 
944  // Description:
945  // Some constants
946  //BTX
947  static int SelectPreviousButtonId;
948  static int SelectNextButtonId;
949  static int AddButtonId;
950  static int ApplyButtonId;
951  static int UpdateButtonId;
952  static int RemoveButtonId;
953  static int LocateButtonId;
954  static int EmailButtonId;
955  static int LoadButtonId;
956  static int FilterButtonId;
957  //ETX
958 
959  // Description:
960  // Access to the button label
961  virtual const char* GetSelectPreviousButtonLabel();
962  virtual const char* GetSelectNextButtonLabel();
963  virtual const char* GetAddButtonLabel();
964  virtual const char* GetApplyButtonLabel();
965  virtual const char* GetUpdateButtonLabel();
966  virtual const char* GetRemoveButtonLabel();
967  virtual const char* GetRemoveAllButtonLabel();
968  virtual const char* GetLocateButtonLabel();
969  virtual const char* GetEmailButtonLabel();
970  virtual const char* GetLoadButtonLabel();
971  virtual const char* GetFilterButtonLabel();
972 
973  // Description:
974  // Delete all presets, i.e. deallocate all presets and remove them
975  // from the pool. Does not delete/remove any rows, see RemoveAllPresets()
976  // to both delete all presets and update the table accordingly.
977  // Return the number of presets deleted
978  virtual int DeleteAllPresets();
979 
980  // Description:
981  // Return the number of selected presets with filename
982  virtual int GetNumberOfSelectedPresetsWithFileName();
983 
984  // Description:
985  // Manage the preset Id to row index cache.
986  virtual void SetPresetIdToRowIndexCacheEntry(int id, int row_index);
987  virtual int GetPresetIdToRowIndexCacheEntry(int id);
988  virtual void InvalidatePresetIdToRowIndexCache();
989 
990  // Description:
991  // Manage the row index to preset Id cache.
992  virtual void SetRowIndexToPresetIdCacheEntry(int row_index, int id);
993  virtual int GetRowIndexToPresetIdCacheEntry(int row_index);
994  virtual void InvalidateRowIndexToPresetIdCache();
995 
996  // Description:
997  // Processes the events that are passed through CallbackCommand (or others).
998  // Subclasses can oberride this method to process their own events, but
999  // should call the superclass too.
1000  virtual void ProcessCallbackCommandEvents(
1001  vtkObject *caller, unsigned long event, void *calldata);
1002 
1003  // Description:
1004  // Constrain the number of presets (given MaximumNumberOfPresets).
1005  virtual void ConstrainNumberOfPresets();
1006 
1007  // Description:
1008  // Set the creation time of a preset.
1009  // Not a public method, but subclass may have a need to set it manually,
1010  // say if the presets are serialized to disk, one may want to load/bring
1011  // them back with the same creation time as when they were first created.
1012  // Return 0 on error.
1013  virtual int SetPresetCreationTime(int id, vtkTypeInt64 value);
1014 
1015 private:
1016 
1017  vtkKWPresetSelector(const vtkKWPresetSelector&); // Not implemented
1018  void operator=(const vtkKWPresetSelector&); // Not implemented
1019 };
1020 
1021 #endif