debian/tmp/usr/include/KWWidgets/vtkKWPresetSelector.h

Go to the documentation of this file.
00001 /*=========================================================================
00002 
00003   Module:    $RCSfile: vtkKWPresetSelector.h,v $
00004 
00005   Copyright (c) Kitware, Inc.
00006   All rights reserved.
00007   See Copyright.txt or http://www.kitware.com/Copyright.htm for details.
00008 
00009      This software is distributed WITHOUT ANY WARRANTY; without even
00010      the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
00011      PURPOSE.  See the above copyright notice for more information.
00012 
00013 =========================================================================*/
00014 // .NAME vtkKWPresetSelector - a preset selector.
00015 // .SECTION Description
00016 // This class is the basis for a preset selector framework. 
00017 // Presets can be added to the selector and identified by unique IDs. 
00018 // They can be assigned pre-defined fields like a group, a filename, 
00019 // a comment, a thumbnail and a screenshot, as well as an unlimited number
00020 // of user-defined slots.
00021 // Presets are listed vertically in a table list widget (vtkKWMultiColumnList),
00022 // one by row. Each column is used to display one of the predefined field.
00023 // The class can be used as-is, or extended to support more columns or
00024 // features, as examplified in the vtkKWWindowLevelPresetSelector and
00025 // vtkKWVolumePropertyPresetSelector sub-classes.
00026 // Several callbacks can be specified to enable external code to
00027 // add presets, apply presets, update them, etc.
00028 // presets. 
00029 // .SECTION Thanks
00030 // This work is part of the National Alliance for Medical Image
00031 // Computing (NAMIC), funded by the National Institutes of Health
00032 // through the NIH Roadmap for Medical Research, Grant U54 EB005149.
00033 // Information on the National Centers for Biomedical Computing
00034 // can be obtained from http://nihroadmap.nih.gov/bioinformatics.
00035 // .SECTION See Also
00036 // vtkKWWindowLevelPresetSelector vtkKWVolumePropertyPresetSelector
00037 
00038 #ifndef __vtkKWPresetSelector_h
00039 #define __vtkKWPresetSelector_h
00040 
00041 #include "vtkKWCompositeWidget.h"
00042 
00043 class vtkImageData;
00044 class vtkKWIcon;
00045 class vtkKWMultiColumnListWithScrollbars;
00046 class vtkKWPresetSelectorInternals;
00047 class vtkKWPushButtonSet;
00048 class vtkRenderWindow;
00049 class vtkKWMenu;
00050 class vtkKWToolbar;
00051 class vtkKWLabelWithLabel;
00052 
00053 class KWWidgets_EXPORT vtkKWPresetSelector : public vtkKWCompositeWidget
00054 {
00055 public:
00056   static vtkKWPresetSelector* New();
00057   vtkTypeRevisionMacro(vtkKWPresetSelector, vtkKWCompositeWidget);
00058   void PrintSelf(ostream& os, vtkIndent indent);
00059 
00060   // Description:
00061   // Add a new preset to the end of the list, or insert a preset in front
00062   // of another preset, given its Id (if passed -1 as Id, insert at the 
00063   // beginning).
00064   // Return the unique Id of the new preset, or -1 on error.
00065   virtual int AddPreset();
00066   virtual int InsertPreset(int id);
00067 
00068   // Description:
00069   // Query if pool has given preset.
00070   // Return 1 if in the pool, 0 otherwise
00071   virtual int HasPreset(int id);
00072 
00073   // Description:
00074   // Set/Get the group associated to a preset.
00075   // This provide a way of grouping presets.
00076   // The group field is not displayed as a column by default, but this
00077   // can be changed using the SetGroupColumnVisibility() method.
00078   // This column can not be edited by default, but this can be changed by
00079   // a subclass.
00080   // Return 1 on success, 0 on error
00081   virtual int SetPresetGroup(int id, const char *group);
00082   virtual const char* GetPresetGroup(int id);
00083 
00084   // Description:
00085   // Set/Get the visibility of the group column. Hidden by default.
00086   // No effect if called before Create().
00087   virtual void SetGroupColumnVisibility(int);
00088   virtual int GetGroupColumnVisibility();
00089   vtkBooleanMacro(GroupColumnVisibility, int);
00090 
00091   // Description:
00092   // Set/Get the title of the group column.
00093   // No effect if called before Create().
00094   virtual void SetGroupColumnTitle(const char *);
00095   virtual const char* GetGroupColumnTitle();
00096 
00097   // Description:
00098   // Set/Get the comment associated to a preset.
00099   // This provide a way to create a small description or comment for
00100   // each preset. 
00101   // The comment field is displayed as a column by default, but this 
00102   // can be changed using the SetCommentColumnVisibility() method.
00103   // This column can be edited by default, by double-clicking
00104   // on the corresponding table cell.
00105   // Return 1 on success, 0 on error
00106   virtual int SetPresetComment(int id, const char *comment);
00107   virtual const char* GetPresetComment(int id);
00108 
00109   // Description:
00110   // Set/Get the visibility of the comment column.
00111   // No effect if called before Create().
00112   virtual void SetCommentColumnVisibility(int);
00113   virtual int GetCommentColumnVisibility();
00114   vtkBooleanMacro(CommentColumnVisibility, int);
00115 
00116   // Description:
00117   // Set/Get the filename associated to a preset.
00118   // This field is neither used nor displayed in this implementation
00119   // but is provided for subclasses that need to save preset to disks
00120   // and keep track of the corresponding filename.
00121   // A method is available to retrieve the Id of the preset that has
00122   // been assigned a specific filename (if passed a relative name, compare
00123   // the filenames without their paths).
00124   // Return 1 on success, 0 on error (id on success, -1 otherwise)
00125   virtual int SetPresetFileName(int id, const char *filename);
00126   virtual const char* GetPresetFileName(int id);
00127   virtual int GetIdOfPresetWithFileName(const char *filename);
00128 
00129   // Description:
00130   // Get the creation time of a preset, as returned by
00131   // the vtksys::SystemTools::GetTime() method, but in milliseconds.
00132   // This field is not displayed in this implementation, but is
00133   // used internally in the thumbnail column so that sorting by
00134   // "thumbnail" will actually sort by creation time.
00135   // Return 0 on error.
00136   virtual vtkTypeInt64 GetPresetCreationTime(int id);
00137 
00138   // Description:
00139   // Set/Get the thumbnail and screenshot associated to a preset.
00140   // The thumbnail is displayed in the thumbnail column, and the screenshot 
00141   // is displayed as a pop-up when the user hovers over that thumbnail. 
00142   // The thumbnail field is not displayed as a column by default, but this 
00143   // can be changed using the SetThumbnailColumnVisibility() method.
00144   // Note that the vtkKWIcon object passed as parameter is neither
00145   // stored nor Register()'ed, only a copy is stored (and updated each
00146   // time the Set... method is called later on).
00147   virtual vtkKWIcon* GetPresetThumbnail(int id);
00148   virtual int SetPresetThumbnail(int id, vtkKWIcon *icon);
00149   virtual vtkKWIcon* GetPresetScreenshot(int id);
00150   virtual int SetPresetScreenshot(int id, vtkKWIcon *icon);
00151 
00152   // Description:
00153   // Set/Get the visibility of the thumbnail column.
00154   // No effect if called before Create().
00155   virtual void SetThumbnailColumnVisibility(int);
00156   virtual int GetThumbnailColumnVisibility();
00157   vtkBooleanMacro(ThumbnailColumnVisibility, int);
00158 
00159   // Description:
00160   // Build both the thumbnail and screenshot for a specific preset using a
00161   // vtkImageData. The thumbnail is constructed by resampling the image to
00162   // fit the ThumbnailSize constraint. The screenshot is constructed by
00163   // resampling the image to fit the ScreenshotSize  constraint. 
00164   // This method is typically useful to build both thumbnail
00165   // and screenshot from a single larger image (or screenshot).
00166   // A similar method can be passed a vtkRenderWindow instead of a 
00167   // vtkImageData; in that case, the window contents is grabbed and used
00168   // to build both thumbnail and screenshot.
00169   // Both thumbnail and screenshot icons can be retrieved.
00170   // Return 1 on success, 0 on error
00171   virtual int BuildPresetThumbnailAndScreenshotFromImage(
00172     int id, vtkImageData *image);
00173   virtual int BuildPresetThumbnailAndScreenshotFromRenderWindow(
00174     int id, vtkRenderWindow *win);
00175 
00176   // Description:
00177   // Flip the thumbnail and screenshot vertically for a specific preset
00178   // Return 1 on success, 0 on error
00179   virtual int FlipPresetThumbnailAndScreenshotVertically(int id);
00180 
00181   // Description:
00182   // Set/Get the thumbnail size.
00183   // Changing the size will not resize the current thumbnails, but will
00184   // affect the presets added to the selector later on using the
00185   // BuildPresetThumbnailAndScreenshotFromImage method.
00186   vtkSetClampMacro(ThumbnailSize,int,8,512);
00187   vtkGetMacro(ThumbnailSize,int);
00188 
00189   // Description:
00190   // Set/Get the screenshot size, i.e. the image that appears as
00191   // a popup when the mouse is on top of the thumbnail.
00192   // Changing the size will not resize the current screenshots, but will
00193   // affect the presets added to the selector later on using the
00194   // BuildPresetThumbnailAndScreenshotFromImage method.
00195   vtkSetClampMacro(ScreenshotSize,int,8,2048);
00196   vtkGetMacro(ScreenshotSize,int);
00197 
00198   // Description:
00199   // Set/Get a preset user slot.
00200   // An unlimited number of slots can be added to a preset. Each slot is
00201   // identified by a name (string). Methods are provided to store
00202   // and retrieve various types of data (double, int, string, generic pointer, 
00203   // pointer to vtkObject). Note a SetPresetUserSlotAsObject *does* call
00204   // Register() on the object passed as parameter, and will call UnRegister()
00205   // once it is time to remove/deallocate all presets (either automatically
00206   // when this instance is deleted or programatically).
00207   // Note that setting the value of a slot will automatically call
00208   // ScheduleUpdatePresetRow for the specific preset if the value was
00209   // different than the previous value.
00210   // Return 1 on success, 0 on error
00211   //BTX
00212   enum 
00213   {
00214     UserSlotDoubleType = 0,
00215     UserSlotIntType,
00216     UserSlotUnsignedLongType,
00217     UserSlotInt64Type,
00218     UserSlotStringType,
00219     UserSlotPointerType,
00220     UserSlotObjectType,
00221     UserSlotUnknownType
00222   };
00223   //ETX
00224   virtual int HasPresetUserSlot(
00225     int id, const char *slot_name);
00226   virtual int GetPresetUserSlotType(
00227     int id, const char *slot_name);
00228   virtual int DeletePresetUserSlot(
00229     int id, const char *slot_name);
00230   virtual int SetPresetUserSlotAsDouble(
00231     int id, const char *slot_name, double value);
00232   virtual double GetPresetUserSlotAsDouble(
00233     int id, const char *slot_name);
00234   virtual int SetPresetUserSlotAsInt(
00235     int id, const char *slot_name, int value);
00236   virtual int GetPresetUserSlotAsInt(
00237     int id, const char *slot_name);
00238   virtual int SetPresetUserSlotAsUnsignedLong(
00239     int id, const char *slot_name, unsigned long value);
00240   virtual unsigned long GetPresetUserSlotAsUnsignedLong(
00241     int id, const char *slot_name);
00242   virtual int SetPresetUserSlotAsInt64(
00243     int id, const char *slot_name, vtkTypeInt64 value);
00244   virtual vtkTypeInt64 GetPresetUserSlotAsInt64(
00245     int id, const char *slot_name);
00246   virtual int SetPresetUserSlotAsString(
00247     int id, const char *slot_name, const char *value);
00248   virtual const char* GetPresetUserSlotAsString(
00249     int id, const char *slot_name);
00250   virtual int SetPresetUserSlotAsPointer(
00251     int id, const char *slot_name, void *ptr);
00252   virtual void* GetPresetUserSlotAsPointer(
00253     int id, const char *slot_name);
00254   virtual int SetPresetUserSlotAsObject(
00255     int id, const char *slot_name, vtkObject *obj);
00256   virtual vtkObject* GetPresetUserSlotAsObject(
00257     int id, const char *slot_name);
00258 
00259   // Description:
00260   // Most (if not all) of the information associated to a preset (say group, 
00261   // comment, filename, creation time, thumbnail and screenshot) is stored
00262   // under the hood as user slots using the corresponding API (i.e. 
00263   // Set/GetPresetUserSlotAs...()). Since each slot requires a unique name,
00264   // the following methods are provided to retrieve the slot name for
00265   // the default preset fields. This can be useful to avoid collision between
00266   // the default slots and your own user slots. Note that the default slot
00267   // names can be changed too, but doing so will not transfer the value
00268   // stored at the old slot name to the new slot name (it is up to you to do
00269   // so, if needed).
00270   virtual void SetPresetGroupSlotName(const char *);
00271   virtual const char* GetPresetGroupSlotName();
00272   virtual void SetPresetCommentSlotName(const char *);
00273   virtual const char* GetPresetCommentSlotName();
00274   virtual void SetPresetFileNameSlotName(const char *);
00275   virtual const char* GetPresetFileNameSlotName();
00276   virtual void SetPresetCreationTimeSlotName(const char *);
00277   virtual const char* GetPresetCreationTimeSlotName();
00278   virtual void SetPresetThumbnailSlotName(const char *);
00279   virtual const char* GetPresetThumbnailSlotName();
00280   virtual void SetPresetScreenshotSlotName(const char *);
00281   virtual const char* GetPresetScreenshotSlotName();
00282 
00283   // Description:
00284   // Set/Get the preset filter constraints.
00285   // The preset filter is a set of constraints that a preset has to match
00286   // to be visible in the preset list. 
00287   // Only string and int slots are supported at the moment.
00288   // At the moment, constraints are expressed as string values (default) or 
00289   // regular expressions that have to match specific user slots. An 
00290   // unlimited number of constraints can be added. 
00291   // For example, if 'slot_name' is 'Modality', and 'value' is
00292   // 'CT', then only those presets which have a 'Modality' user slot with
00293   // a string value of 'CT' will be displayed.
00294   // Note that the constraint type can be changed from regular expression
00295   // to plain character-for-character string comparison using either
00296   // SetPresetFilterUserSlotConstraintToRegularExpression or
00297   // SetPresetFilterUserSlotConstraintToString; however the constraint needs to
00298   // exist for that slot name for this change to be made. When one constraint
00299   // is added, its default type is String, not RegularExpression.
00300   // Use a NULL value for to remove the constraint on a specific slot or
00301   // call DeletePresetFilterUserSlotConstraint
00302   virtual void ClearPresetFilter();
00303   virtual void SetPresetFilterUserSlotConstraint(
00304     const char *slot_name, const char *value);
00305   virtual const char* GetPresetFilterUserSlotConstraint(
00306     const char *slot_name);
00307   virtual void DeletePresetFilterUserSlotConstraint(const char *slot_name);
00308   virtual void SetPresetFilterUserSlotConstraintToRegularExpression(
00309     const char *slot_name);
00310   virtual void SetPresetFilterUserSlotConstraintToString(
00311     const char *slot_name);
00312 
00313   // Description:
00314   // Add a preset filter constraint on the preset group field.
00315   virtual void SetPresetFilterGroupConstraint(const char *value);
00316   virtual const char* GetPresetFilterGroupConstraint();
00317 
00318   // Description:
00319   // Query if a given preset matches the current preset filter constraints.
00320   // Return 1 if match or if no filter was defined, 0 otherwise
00321   virtual int IsPresetFiltered(int id);
00322 
00323   // Description:
00324   // Get the number of presets, or the number of presets with a specific
00325   // group, or the number of visible presets, i.e. the presets that are
00326   // displayed according to the preset filters for example.
00327   virtual int GetNumberOfPresets();
00328   virtual int GetNumberOfPresetsWithGroup(const char *group);
00329   virtual int GetNumberOfVisiblePresets();
00330 
00331   // Description:
00332   // Set/Get the maximum number of presets. When this number is passed, the 
00333   // oldest preset (according to the PresetCreationTime) is deleted 
00334   // automatically. Set it to 0 (default) to allow for unlimited number
00335   // of presets.
00336   vtkGetMacro(MaximumNumberOfPresets, int);
00337   virtual void SetMaximumNumberOfPresets(int);
00338 
00339   // Description:
00340   // Query if a given preset is visible (i.e. displayed in the list).
00341   // Some presets can be hidden, for example if they do not match
00342   // the current preset filter constraints.
00343   virtual int GetPresetVisibility(int id);
00344 
00345   // Description:
00346   // Retrieve the Id of the nth-preset, or the id of the
00347   // nth preset with a given group.
00348   // Return id on success, -1 otherwise
00349   virtual int GetIdOfNthPreset(int index);
00350   virtual int GetIdOfNthPresetWithGroup(int index, const char *group);
00351 
00352   // Description:
00353   // Retrieve the Id of the preset at a given row in the table, or
00354   // the row of a given preset.
00355   // Return id or row index on success, -1 otherwise
00356   virtual int GetIdOfPresetAtRow(int row_index);
00357   virtual int GetPresetRow(int id);
00358 
00359   // Description:
00360   // Retrieve the rank of the nth preset with a given group
00361   // (i.e. the nth-preset with a given group).
00362   // This rank can then be used to retrieve the preset id using
00363   // the GetIdOfNthPreset() method.
00364   // Return rank on success, -1 otherwise
00365   virtual int GetRankOfNthPresetWithGroup(int index, const char *group);
00366 
00367   // Description:
00368   // Remove a preset, or all of them, or all of the presets
00369   // with the same group.
00370   // Return 1 on success, 0 on error
00371   virtual int RemovePreset(int id);
00372   virtual int RemoveAllPresets();
00373   virtual int RemoveAllPresetsWithGroup(const char *group);
00374 
00375   // Description:
00376   // Select a preset, clear the selection.
00377   virtual void SelectPreset(int id);
00378   virtual void SelectPreviousPreset();
00379   virtual void SelectNextPreset();
00380   virtual void ClearSelection();
00381   virtual int GetIdOfSelectedPreset();
00382 
00383   // Description:
00384   // Set/Get the list height (in number of items) or width (in chars)
00385   // No effect if called before Create().
00386   virtual void SetListHeight(int);
00387   virtual int GetListHeight();
00388   virtual void SetListWidth(int);
00389   virtual int GetListWidth();
00390 
00391   // Description:
00392   // Set/Get the base icons to use for the preset buttons (and the toolbar).
00393   // The base icon has to be in RGBA format, and will be composited against
00394   // a few different smaller icons to represent each action; for example,
00395   // a '+' sign will be composited on top of the base icon for the 
00396   // "Add Preset" button.
00397   vtkGetObjectMacro(PresetButtonsBaseIcon, vtkKWIcon);
00398   virtual void SetPresetButtonsBaseIcon(vtkKWIcon *icon);
00399   virtual void SetPresetButtonsBaseIconToPredefinedIcon(int icon_index);
00400 
00401   // Description:
00402   // Set/Get the visibility of the select spin buttons.
00403   // The select spin button are two buttons that can be used
00404   // to select the next or previous preset in the list.
00405   // Note that if ApplyPresetOnSelection is On, this will also apply
00406   // the preset at the same time, thus providing a quick way to
00407   // loop over all presets and apply them.
00408   virtual void SetSelectSpinButtonsVisibility(int);
00409   vtkGetMacro(SelectSpinButtonsVisibility,int);
00410   vtkBooleanMacro(SelectSpinButtonsVisibility,int);
00411 
00412   // Description:
00413   // Set/Get the visibility of the locate preset button and the "Locate" menu
00414   // entry in the context menu (hidden by default).
00415   // If visible, triggering this button will locate all selected presets
00416   // by calling the GetPresetFileName method and trying to open
00417   // the directory they are in and select the proper file.
00418   // Win32 only at the moment.
00419   virtual void SetLocateButtonVisibility(int);
00420   vtkGetMacro(LocateButtonVisibility,int);
00421   vtkBooleanMacro(LocateButtonVisibility,int);
00422   vtkSetMacro(LocateMenuEntryVisibility,int);
00423   vtkGetMacro(LocateMenuEntryVisibility,int);
00424   vtkBooleanMacro(LocateMenuEntryVisibility,int);
00425 
00426   // Description:
00427   // Set/Get the visibility of the email preset button and the "Email" menu 
00428   // entry in the context menu (hidden by default).
00429   // If visible, triggering this button will email all selected presets
00430   // as attachments. The attachment location is retrieved by calling
00431   // the GetPresetFileName method. Win32/MAPI only at the moment.
00432   virtual void SetEmailButtonVisibility(int);
00433   vtkGetMacro(EmailButtonVisibility,int);
00434   vtkBooleanMacro(EmailButtonVisibility,int);
00435   vtkSetMacro(EmailMenuEntryVisibility,int);
00436   vtkGetMacro(EmailMenuEntryVisibility,int);
00437   vtkBooleanMacro(EmailMenuEntryVisibility,int);
00438 
00439   // Description:
00440   // Set/Get the body of the email that will be sent alongside the attached
00441   // preset when the "Email Preset" button or menu entry is triggered.
00442   // Note that it will still appear after a shot paragraph describing which
00443   // application sent that preset, the location of the preset on the sender's
00444   // computer, the comment associated to the preset and its creation time.
00445   vtkSetStringMacro(EmailBody);
00446   vtkGetStringMacro(EmailBody);
00447 
00448   // Description:
00449   // Set/Get the visibility of the remove preset button or the "Remove" entry
00450   // in the context menu (visible by default).
00451   // If visible, triggering this button will remove all selected presets and
00452   // eventually call the callbacks that was set using SetPresetRemoveCommand.
00453   virtual void SetRemoveButtonVisibility(int);
00454   vtkGetMacro(RemoveButtonVisibility,int);
00455   vtkBooleanMacro(RemoveButtonVisibility,int);
00456   vtkGetMacro(RemoveMenuEntryVisibility,int);
00457   vtkSetMacro(RemoveMenuEntryVisibility,int);
00458   vtkBooleanMacro(RemoveMenuEntryVisibility,int);
00459 
00460   // Description:
00461   // Set/Get the visibility of the filter button (hidden by default).
00462   // If visible, clicking on this button will bring the a popup menu 
00463   // presenting all the unique values that were collected in the
00464   // FilterButtonSlotName slot for all presets.
00465   // Each one can be turn on and off, which will update the 
00466   // PresetFilterUserSlotConstraint automatically for that slot.
00467   virtual void SetFilterButtonVisibility(int);
00468   vtkGetMacro(FilterButtonVisibility,int);
00469   vtkBooleanMacro(FilterButtonVisibility,int);
00470   vtkSetStringMacro(FilterButtonSlotName);
00471   vtkGetStringMacro(FilterButtonSlotName);
00472 
00473   // Description:
00474   // Set/Get the visibility of the help message.
00475   virtual void SetHelpLabelVisibility(int);
00476   vtkGetMacro(HelpLabelVisibility,int);
00477   vtkBooleanMacro(HelpLabelVisibility,int);
00478   vtkGetObjectMacro(HelpLabel, vtkKWLabelWithLabel);
00479   virtual void SetHelpLabelText(const char *);
00480 
00481   // Description:
00482   // Specifies a command to associate with the widget. This command is 
00483   // typically invoked when the "add preset" button is pressed.
00484   // This gives the opportunity for the application to check and collect the
00485   // relevant information to store in a new preset. The application is then
00486   // free to add the preset (using the AddPreset() method) and set its
00487   // fields independently (using the SetPresetGroup(), SetPresetComment(),
00488   // SetPreset...() methods).
00489   // Note that if not set, the "add preset" button is not visible.
00490   // The 'object' argument is the object that will have the method called on
00491   // it. The 'method' argument is the name of the method to be called and any
00492   // arguments in string form. If the object is NULL, the method is still
00493   // evaluated as a simple command. 
00494   // The following output is expected from the command:
00495   // - the unique id of the preset that was added (by calling AddPreset()), 
00496   //   -1 otherwise
00497   virtual void SetPresetAddCommand(vtkObject *object, const char *method);
00498 
00499   // Description:
00500   // Specifies a command to associate with the widget. This command is 
00501   // typically invoked when the "update selected preset" button
00502   // is pressed. This gives the opportunity for the application to check and
00503   // collect the relevant information to update in the preset. The application
00504   // is then free to update the preset's fields independently (using the
00505   // SetPresetGroup(), SetPresetComment(), SetPreset...() methods).
00506   // Note that if this command is not set, the corresponding 
00507   // "update selected preset" button is not visible.
00508   // Note that if this command is not set, the corresponding "Update" entry 
00509   // is not shown in the context menu.
00510   // The 'object' argument is the object that will have the method called on
00511   // it. The 'method' argument is the name of the method to be called and any
00512   // arguments in string form. If the object is NULL, the method is still
00513   // evaluated as a simple command. 
00514   // The following parameters are also passed to the command:
00515   // - the id of the preset to update: int
00516   virtual void SetPresetUpdateCommand(vtkObject *object, const char *method);
00517 
00518   // Description:
00519   // Specifies a command to associate with the widget. This command is 
00520   // typically invoked when the "apply selected preset"  button is pressed, 
00521   // or when ApplyPresetOnSelection is On and the user
00522   // applies a preset by selecting it directly. This gives the opportunity
00523   // for the application to query the preset's fields independently (using the
00524   // GetPresetGroup(), GetPresetComment(), GetPreset...() methods) and
00525   // apply those values to the relevant objects.
00526   // Note that if this command is not set or if ApplyPresetOnSelection is On, 
00527   // the corresponding "apply selected preset" button is not visible.
00528   // Note that if this command is not set, the corresponding "Apply" entry 
00529   // is not shown in the context menu.
00530   // The 'object' argument is the object that will have the method called on
00531   // it. The 'method' argument is the name of the method to be called and any
00532   // arguments in string form. If the object is NULL, the method is still
00533   // evaluated as a simple command. 
00534   // The following parameters are also passed to the command:
00535   // - the id of the preset to apply: int
00536   virtual void SetPresetApplyCommand(vtkObject *object, const char *method);
00537 
00538   // Description:
00539   // Set/Get if a preset should be applied directly when it is selected by a
00540   // single-click, or only when the "apply selected preset" button is pressed.
00541   // If set, only one preset can be selected at a time (if not, multiple
00542   // preset can be selected, and removed for example).
00543   // Note that if set, the "apply selected preset" button is not visible.
00544   virtual void SetApplyPresetOnSelection(int);
00545   vtkGetMacro(ApplyPresetOnSelection,int);
00546   vtkBooleanMacro(ApplyPresetOnSelection,int);
00547 
00548   // Description:
00549   // Specifies a command to associate with the widget. This command is 
00550   // typically invoked when the "remove selected preset"
00551   // button is pressed. This command is called *before* the preset is
00552   // removed from the pool: this gives the opportunity for the application 
00553   // to query the preset's fields independently (using the
00554   // GetPresetGroup(), GetPresetComment(), GetPreset...() methods),
00555   // decide if the preset should be removed or not, and delete it from
00556   // its internal structures accordingly, if needed.
00557   // The 'object' argument is the object that will have the method called on
00558   // it. The 'method' argument is the name of the method to be called and any
00559   // arguments in string form. If the object is NULL, the method is still
00560   // evaluated as a simple command. 
00561   // The following parameters are also passed to the command:
00562   // - the id of the preset to remove: int
00563   // The following output is expected from the command:
00564   // - whereas the preset is really to be removed (1) or not (0): int
00565   virtual void SetPresetRemoveCommand(vtkObject *object, const char *method);
00566 
00567   // Description:
00568   // Specifies a command to associate with the widget. This command is 
00569   // typically invoked when a preset has been removed as a result of
00570   // pressing the "remove selected preset" button. As opposed to the
00571   // PresetRemoveCommand, this command is called *after* the preset is
00572   // removed from the pool and only if it has been removed (its Id is
00573   // therefore not passed to the callback as a parameter). Do not confuse
00574   // this command with PresetRemoveCommand which gives the opportunity for 
00575   // the application to decide if the preset should be removed or not.
00576   // The 'object' argument is the object that will have the method called on
00577   // it. The 'method' argument is the name of the method to be called and any
00578   // arguments in string form. If the object is NULL, the method is still
00579   // evaluated as a simple command. 
00580   virtual void SetPresetRemovedCommand(vtkObject *object, const char *method);
00581 
00582   // Description:
00583   // Set/Get if the user should be prompted before removing one or
00584   // more presets using "remove selected preset" button.
00585   vtkSetMacro(PromptBeforeRemovePreset, int);
00586   vtkGetMacro(PromptBeforeRemovePreset, int);
00587   vtkBooleanMacro(PromptBeforeRemovePreset, int);
00588 
00589   // Description:
00590   // Specifies a command to associate with the widget. This command is 
00591   // typically invoked when the preset has been changed using direct
00592   // user-interaction on the widget interface. 
00593   // This includes double-clicking on a table cell (the comment field for
00594   // example) and editing the contents of the cell directly, when allowed.
00595   // This gives the opportunity for the application to query the preset's
00596   // fields independently (using the GetPresetGroup(), GetPresetComment(), 
00597   // GetPreset...() methods), and update its internal structures accordingly, 
00598   // if needed.
00599   // The 'object' argument is the object that will have the method called on
00600   // it. The 'method' argument is the name of the method to be called and any
00601   // arguments in string form. If the object is NULL, the method is still
00602   // evaluated as a simple command. 
00603   // The following parameters are also passed to the command:
00604   // - the id of the preset that has changed: int
00605   virtual void SetPresetHasChangedCommand(
00606     vtkObject *object, const char *method);
00607 
00608   // Description:
00609   // Specifies a command to associate with the widget. This command is 
00610   // typically invoked when the "load preset" button is pressed.
00611   // This gives the opportunity for the application to invoke a file dialog,
00612   // let the user pick a preset file, load it and collect the relevant 
00613   // information to store in a new preset. The application is then
00614   // free to add the preset (using the AddPreset() method) and set its
00615   // fields independently (using the SetPresetGroup(), SetPresetComment(),
00616   // SetPreset...() methods).
00617   // Note that if not set, the "load preset" button is not visible.
00618   // The 'object' argument is the object that will have the method called on
00619   // it. The 'method' argument is the name of the method to be called and any
00620   // arguments in string form. If the object is NULL, the method is still
00621   // evaluated as a simple command. 
00622   // The following output is expected from the command:
00623   // - the unique id of the preset that was loaded and added (by calling
00624   //   AddPreset()), -1 otherwise
00625   virtual void SetPresetLoadCommand(vtkObject *object, const char *method);
00626 
00627   // Description:
00628   // Specifies a command to associate with the widget. This command is 
00629   // typically invoked when the preset filtering has changed, i.e. a filter
00630   // constraint has been added/removed (see, ClearPresetFilter or
00631   // SetPresetFilterUserSlotConstraint).
00632   // The 'object' argument is the object that will have the method called on
00633   // it. The 'method' argument is the name of the method to be called and any
00634   // arguments in string form. If the object is NULL, the method is still
00635   // evaluated as a simple command. 
00636   virtual void SetPresetFilteringHasChangedCommand(
00637     vtkObject *object, const char *method);
00638 
00639   // Description:
00640   // Refresh the interface.
00641   virtual void Update();
00642 
00643   // Description:
00644   // Update the "enable" state of the object and its internal parts.
00645   // Depending on different Ivars (this->Enabled, the application's 
00646   // Limited Edition Mode, etc.), the "enable" state of the object is updated
00647   // and propagated to its internal parts/subwidgets. This will, for example,
00648   // enable/disable parts of the widget UI, enable/disable the visibility
00649   // of 3D widgets, etc.
00650   virtual void UpdateEnableState();
00651 
00652   // Description:
00653   // Callback used to refresh the contents of the image cell for each preset
00654   virtual void PresetCellThumbnailCallback(const char*, int, int, const char*);
00655 
00656   // Description:
00657   // Callback invoked when the user starts editing a specific preset field
00658   // located at cell ('row', 'col'), which current contents is 'text'.
00659   // This method returns the value that is to become the initial 
00660   // contents of the temporary embedded widget used for editing: most of the
00661   // time, this is the same value as 'text'.
00662   // The next step (validation) is handled by PresetCellEditEndCallback
00663   virtual const char* PresetCellEditStartCallback(
00664     int row, int col, const char *text);
00665 
00666   // Description:
00667   // Callback invoked when the user ends editing a specific preset field
00668   // located at cell ('row', 'col').
00669   // The main purpose of this method is to perform a final validation of
00670   // the edit window's contents 'text'.
00671   // This method returns the value that is to become the new contents
00672   // for that cell.
00673   // The next step (updating) is handled by PresetCellUpdateCallback
00674   virtual const char* PresetCellEditEndCallback(
00675     int row, int col, const char *text);
00676 
00677   // Description:
00678   // Callback invoked when the user successfully updated the preset field
00679   // located at ('row', 'col') with the new contents 'text', as a result
00680   // of editing the corresponding cell interactively.
00681   virtual void PresetCellUpdatedCallback(int row, int col, const char *text);
00682 
00683   // Description:
00684   // Retrieve the toolbar. Use that method to set the parent of this object to
00685   // a specific widget or toolbar set (vtkKWToolbarSet), before calling 
00686   // CreateToolbar.
00687  virtual vtkKWToolbar* GetToolbar();
00688 
00689   // Description:
00690   // Create the toolbar. If the toolbar has to be placed in a specific location
00691  // in the application, call the GetToolbar method and set the toolbar parent
00692  // beforehand.
00693   virtual void CreateToolbar();
00694 
00695   // Description:
00696   // Some constants
00697   //BTX
00698   static const char *IdColumnName;
00699   static const char *ThumbnailColumnName;
00700   static const char *GroupColumnName;
00701   static const char *CommentColumnName;
00702   //ETX
00703 
00704   // Description:
00705   // Callbacks. Internal, do not use.
00706   virtual int  PresetAddCallback();
00707   virtual void PresetApplyCallback();
00708   virtual void PresetApplyCallback(int id);
00709   virtual void PresetUpdateCallback();
00710   virtual void PresetUpdateCallback(int id);
00711   virtual void PresetRemoveCallback();
00712   virtual void PresetRemoveAllCallback();
00713   virtual void PresetRemoveCallback(int id);
00714   virtual void PresetEmailCallback();
00715   virtual void PresetEmailCallback(int id);
00716   virtual void PresetLocateCallback();
00717   virtual void PresetLocateCallback(int id);
00718   virtual void PresetSelectionCallback();
00719   virtual void PresetSelectionChangedCallback();
00720   virtual void PresetRightClickCallback(int row, int col, int x, int y);
00721   virtual int  PresetLoadCallback();
00722   virtual void PresetFilterCallback();
00723   virtual void PresetFilterApplyCallback(const char *regexp);
00724   virtual void UpdatePresetRowCallback(int id);
00725   virtual void UpdatePresetRowsCallback();
00726   virtual void ColumnSortedCallback();
00727   virtual void RowMovedCallback();
00728   virtual void SchedulePresetSelectionCallback();
00729   virtual void SchedulePresetSelectionChangedCallback();
00730 
00731   // Description:
00732   // Access to the internal multicolumn list.
00733   // This is temporary, this internal widget may change.
00734   vtkGetObjectMacro(PresetList, vtkKWMultiColumnListWithScrollbars);
00735 
00736 protected:
00737   vtkKWPresetSelector();
00738   ~vtkKWPresetSelector();
00739 
00740   // Description:
00741   // Create the widget.
00742   virtual void CreateWidget();
00743   
00744   // Description:
00745   // Create the columns.
00746   // Subclasses should override this method to add their own columns and
00747   // display their own preset fields (do not forget to call the superclass
00748   // first).
00749   virtual void CreateColumns();
00750 
00751   // Description:
00752   // Create the preset buttons in the toolbar.
00753   // Subclasses should override this method to add their own toolbar buttons
00754   // (do not forget to call the superclass first).
00755   virtual void CreateToolbarPresetButtons(vtkKWToolbar*, int use_separators);
00756 
00757   // Description:
00758   // Update the toolbar preset buttons state/visibility.
00759   virtual void UpdateToolbarPresetButtons(vtkKWToolbar*);
00760 
00761   // Description:
00762   // Set the toolbar preset buttons icons.
00763   // Subclasses should override this method to set their own icons
00764   // (do not forget to call the superclass first).
00765   virtual void SetToolbarPresetButtonsIcons(vtkKWToolbar*);
00766 
00767   // Description:
00768   // Set the toolbar preset buttons balloon help strings
00769   // Subclass can override this method to change the help strings
00770   // associated to the buttons.
00771   virtual void SetToolbarPresetButtonsHelpStrings(vtkKWToolbar*);
00772 
00773   // Description:
00774   // Configure a new preset.
00775   // Subclasses should override this method to configure a newly allocated
00776   // preset, i.e. assign its internal values (do not forget to call the
00777   // superclass first).
00778   virtual void ConfigureNewPreset(int id);
00779 
00780   // Description:
00781   // Deallocate a preset.
00782   // Subclasses should override this method to release the memory allocated
00783   // by their own preset fields  (do not forget to call the superclass
00784   // first).
00785   virtual void DeAllocatePreset(int id);
00786 
00787   // Description:
00788   // Update the preset row, i.e. add a row for that preset if it is not
00789   // displayed already, hide it if it does not match the filters, and
00790   // update the table columns with the corresponding preset fields.
00791   // Subclass should override this method to display their own fields.
00792   // Return 1 on success, 0 if the row was not (or can not be) updated.
00793   // Subclasses should call the parent's UpdatePresetRow, and abort
00794   // if the result is not 1.
00795   virtual int UpdatePresetRow(int id);
00796   virtual void ScheduleUpdatePresetRow(int id);
00797 
00798   // Description:
00799   // Update the preset row itself in the list, i.e. add or remove a row
00800   // for a specific preset id in the multicolumn list. UpdatePresetRow() and/or
00801   // ScheduleUpdatePresetRow() will call this function first, then add
00802   // the contents of the row itself. Pass/set is_new to 1 if you are 
00803   // sure the preset is new and was never inserted in the list.
00804   // Return row index on success (can be 0), -1 otherwise.
00805   virtual int UpdatePresetRowInMultiColumnList(int id, int is_new = 0);
00806 
00807   vtkKWMultiColumnListWithScrollbars *PresetList;
00808   vtkKWFrame                         *PresetControlFrame;
00809   vtkKWToolbar                       *PresetButtons;
00810   vtkKWToolbar                       *Toolbar;
00811   vtkKWLabelWithLabel                *HelpLabel;
00812   vtkKWMenu                          *ContextMenu;
00813   vtkKWIcon                          *PresetButtonsBaseIcon;
00814  
00815 
00816   int ApplyPresetOnSelection;
00817   int SelectSpinButtonsVisibility;
00818   int EmailButtonVisibility;
00819   int EmailMenuEntryVisibility;
00820   int LocateButtonVisibility;
00821   int LocateMenuEntryVisibility;
00822   int RemoveButtonVisibility;
00823   int RemoveMenuEntryVisibility;
00824   int HelpLabelVisibility;
00825   int FilterButtonVisibility;
00826 
00827   int ThumbnailSize;
00828   int ScreenshotSize;
00829   int PromptBeforeRemovePreset;
00830   int MaximumNumberOfPresets;
00831 
00832   char *EmailBody;
00833   char *FilterButtonSlotName;
00834 
00835   // Description:
00836   // Called when the number of presets has changed.
00837   // Note that the name of this function can be a bit misleading: if 
00838   // MaximumNumberOfPresets is set to a positive number, and the max
00839   // has been reached, this function will *still* be called twice, once
00840   // when the max is passed as a result of adding a preset, and then another
00841   // time when a preset is automatically deleted to get back to the maximum
00842   // value (which is, in most case, what you want to know anyway).
00843   virtual void NumberOfPresetsHasChanged();
00844 
00845   // Description:
00846   // Called when preset filtering has changed, i.e. a filter
00847   // constraint has been added/removed (see, ClearPresetFilter or
00848   // SetPresetFilterUserSlotConstraint).
00849   virtual void PresetFilteringHasChanged();
00850 
00851   // Description:
00852   // Called when preset filtering *may* have changed, the value of a slot has
00853   // changed and that slot was filtered (i.e. had a constraint put on it
00854   // using SetPresetFilterUserSlotConstraint), therefore it is possible that
00855   // preset maybe pass or not pass the filter anymore (IsPresetFiltered).
00856   virtual void PresetFilteringMayHaveChanged();
00857 
00858   // PIMPL Encapsulation for STL containers
00859   //BTX
00860   vtkKWPresetSelectorInternals *Internals;
00861   //ETX
00862 
00863   // Description:
00864   // Update all rows in the list
00865   virtual void UpdatePresetRows();
00866   virtual void ScheduleUpdatePresetRows();
00867   virtual void CancelScheduleUpdatePresetRows();
00868 
00869   char *PresetAddCommand;
00870   virtual int InvokePresetAddCommand();
00871 
00872   char *PresetUpdateCommand;
00873   virtual void InvokePresetUpdateCommand(int id);
00874 
00875   char *PresetApplyCommand;
00876   virtual void InvokePresetApplyCommand(int id);
00877 
00878   char *PresetRemoveCommand;
00879   virtual int InvokePresetRemoveCommand(int id);
00880 
00881   char *PresetRemovedCommand;
00882   virtual void InvokePresetRemovedCommand();
00883 
00884   char *PresetHasChangedCommand;
00885   virtual void InvokePresetHasChangedCommand(int id);
00886 
00887   char *PresetLoadCommand;
00888   virtual int InvokePresetLoadCommand();
00889 
00890   char *PresetFilteringHasChangedCommand;
00891   virtual void InvokePresetFilteringHasChangedCommand();
00892 
00893   // Description:
00894   // Get the index of a given column.
00895   virtual int GetIdColumnIndex();
00896   virtual int GetThumbnailColumnIndex();
00897   virtual int GetGroupColumnIndex();
00898   virtual int GetCommentColumnIndex();
00899 
00900   // Description:
00901   // Pack
00902   virtual void Pack();
00903 
00904   // Description:
00905   // Populate the pop-up context menu that is displayed when right-clicking
00906   // on a give preset. It should replicate the commands available through the
00907   // preset buttons.
00908   virtual void PopulatePresetContextMenu(vtkKWMenu *menu, int id);
00909 
00910   // Description:
00911   // Some constants
00912   //BTX
00913   static int SelectPreviousButtonId;
00914   static int SelectNextButtonId;
00915   static int AddButtonId;
00916   static int ApplyButtonId;
00917   static int UpdateButtonId;
00918   static int RemoveButtonId;
00919   static int LocateButtonId;
00920   static int EmailButtonId;
00921   static int LoadButtonId;
00922   static int FilterButtonId;
00923   //ETX
00924 
00925   // Description:
00926   // Access to the button label
00927   virtual const char* GetSelectPreviousButtonLabel();
00928   virtual const char* GetSelectNextButtonLabel();
00929   virtual const char* GetAddButtonLabel();
00930   virtual const char* GetApplyButtonLabel();
00931   virtual const char* GetUpdateButtonLabel();
00932   virtual const char* GetRemoveButtonLabel();
00933   virtual const char* GetRemoveAllButtonLabel();
00934   virtual const char* GetLocateButtonLabel();
00935   virtual const char* GetEmailButtonLabel();
00936   virtual const char* GetLoadButtonLabel();
00937   virtual const char* GetFilterButtonLabel();
00938   
00939   // Description:
00940   // Delete all presets, i.e. deallocate all presets and remove them
00941   // from the pool. Does not delete/remove any rows, see RemoveAllPresets()
00942   // to both delete all presets and update the table accordingly.
00943   // Return the number of presets deleted
00944   virtual int DeleteAllPresets();
00945 
00946   // Description:
00947   // Return the number of selected presets with filename
00948   virtual int GetNumberOfSelectedPresetsWithFileName();
00949 
00950   // Description:
00951   // Manage the preset Id to row index cache.
00952   virtual void SetPresetIdToRowIndexCacheEntry(int id, int row_index);
00953   virtual int GetPresetIdToRowIndexCacheEntry(int id);
00954   virtual void InvalidatePresetIdToRowIndexCache();
00955 
00956   // Description:
00957   // Manage the row index to preset Id cache.
00958   virtual void SetRowIndexToPresetIdCacheEntry(int row_index, int id);
00959   virtual int GetRowIndexToPresetIdCacheEntry(int row_index);
00960   virtual void InvalidateRowIndexToPresetIdCache();
00961 
00962   // Description:
00963   // Processes the events that are passed through CallbackCommand (or others).
00964   // Subclasses can oberride this method to process their own events, but
00965   // should call the superclass too.
00966   virtual void ProcessCallbackCommandEvents(
00967     vtkObject *caller, unsigned long event, void *calldata);
00968 
00969   // Description:
00970   // Constrain the number of presets (given MaximumNumberOfPresets).
00971   virtual void ConstrainNumberOfPresets();
00972   
00973   // Description:
00974   // Set the creation time of a preset.
00975   // Not a public method, but subclass may have a need to set it manually,
00976   // say if the presets are serialized to disk, one may want to load/bring 
00977   // them back with the same creation time as when they were first created.
00978   // Return 0 on error.
00979   virtual int SetPresetCreationTime(int id, vtkTypeInt64 value);
00980 
00981 private:
00982 
00983   vtkKWPresetSelector(const vtkKWPresetSelector&); // Not implemented
00984   void operator=(const vtkKWPresetSelector&); // Not implemented
00985 };
00986 
00987 #endif