KWWidgets
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   // Description:
00737   // Set the callbacks to be used to create, update, and set the icons and
00738   // help strings on user-defined buttons. These callbacks can be used to
00739   // add buttons to the preset selector toolbar(s), without subclassing it.
00740   // The 'object' argument is the object that will have the method called on
00741   // it. The 'method' argument is the name of the method to be called and any
00742   // arguments in string form. If the object is NULL, the method is still
00743   // evaluated as a simple command. 
00744   // Note that each callback will receive the following parameters:
00745   // CreateUserPresetButtonsCommand: vtkKWToolbar *toolbar, int use_separators
00746   // UpdateUserPresetButtonsCommand: vtkKWToolbar *toolbar
00747   // SetUserPresetButtonsIconsCommand: vtkKWToolbar *toolbar
00748   // SetUserPresetButtonsHelpStringsCommand: vtkKWToolbar *toolbar
00749   virtual void SetCreateUserPresetButtonsCommand(
00750     vtkObject *object, const char *method);
00751   virtual void SetUpdateUserPresetButtonsCommand(
00752     vtkObject *object, const char *method);
00753   virtual void SetSetUserPresetButtonsIconsCommand(
00754     vtkObject *object, const char *method);
00755   virtual void SetSetUserPresetButtonsHelpStringsCommand(
00756     vtkObject *object, const char *method);
00757 
00758 protected:
00759   vtkKWPresetSelector();
00760   ~vtkKWPresetSelector();
00761 
00762   // Description:
00763   // Create the widget.
00764   virtual void CreateWidget();
00765   
00766   // Description:
00767   // Create the columns.
00768   // Subclasses should override this method to add their own columns and
00769   // display their own preset fields (do not forget to call the superclass
00770   // first).
00771   virtual void CreateColumns();
00772 
00773   // Description:
00774   // Create the preset buttons in the toolbar.
00775   // Subclasses should override this method to add their own toolbar buttons
00776   // (do not forget to call the superclass first).
00777   virtual void CreateToolbarPresetButtons(vtkKWToolbar*, int use_separators);
00778 
00779   // Description:
00780   // Update the toolbar preset buttons state/visibility.
00781   virtual void UpdateToolbarPresetButtons(vtkKWToolbar*);
00782 
00783   // Description:
00784   // Set the toolbar preset buttons icons.
00785   // Subclasses should override this method to set their own icons
00786   // (do not forget to call the superclass first).
00787   virtual void SetToolbarPresetButtonsIcons(vtkKWToolbar*);
00788 
00789   // Description:
00790   // Set the toolbar preset buttons balloon help strings
00791   // Subclass can override this method to change the help strings
00792   // associated to the buttons.
00793   virtual void SetToolbarPresetButtonsHelpStrings(vtkKWToolbar*);
00794 
00795   // Description:
00796   // Configure a new preset.
00797   // Subclasses should override this method to configure a newly allocated
00798   // preset, i.e. assign its internal values (do not forget to call the
00799   // superclass first).
00800   virtual void ConfigureNewPreset(int id);
00801 
00802   // Description:
00803   // Deallocate a preset.
00804   // Subclasses should override this method to release the memory allocated
00805   // by their own preset fields  (do not forget to call the superclass
00806   // first).
00807   virtual void DeAllocatePreset(int id);
00808 
00809   // Description:
00810   // Update the preset row, i.e. add a row for that preset if it is not
00811   // displayed already, hide it if it does not match the filters, and
00812   // update the table columns with the corresponding preset fields.
00813   // Subclass should override this method to display their own fields.
00814   // Return 1 on success, 0 if the row was not (or can not be) updated.
00815   // Subclasses should call the parent's UpdatePresetRow, and abort
00816   // if the result is not 1.
00817   virtual int UpdatePresetRow(int id);
00818   virtual void ScheduleUpdatePresetRow(int id);
00819 
00820   // Description:
00821   // Update the preset row itself in the list, i.e. add or remove a row
00822   // for a specific preset id in the multicolumn list. UpdatePresetRow() and/or
00823   // ScheduleUpdatePresetRow() will call this function first, then add
00824   // the contents of the row itself. Pass/set is_new to 1 if you are 
00825   // sure the preset is new and was never inserted in the list.
00826   // Return row index on success (can be 0), -1 otherwise.
00827   virtual int UpdatePresetRowInMultiColumnList(int id, int is_new = 0);
00828 
00829   vtkKWMultiColumnListWithScrollbars *PresetList;
00830   vtkKWFrame                         *PresetControlFrame;
00831   vtkKWToolbar                       *PresetButtons;
00832   vtkKWToolbar                       *Toolbar;
00833   vtkKWLabelWithLabel                *HelpLabel;
00834   vtkKWMenu                          *ContextMenu;
00835   vtkKWIcon                          *PresetButtonsBaseIcon;
00836  
00837 
00838   int ApplyPresetOnSelection;
00839   int SelectSpinButtonsVisibility;
00840   int EmailButtonVisibility;
00841   int EmailMenuEntryVisibility;
00842   int LocateButtonVisibility;
00843   int LocateMenuEntryVisibility;
00844   int RemoveButtonVisibility;
00845   int RemoveMenuEntryVisibility;
00846   int HelpLabelVisibility;
00847   int FilterButtonVisibility;
00848 
00849   int ThumbnailSize;
00850   int ScreenshotSize;
00851   int PromptBeforeRemovePreset;
00852   int MaximumNumberOfPresets;
00853 
00854   char *EmailBody;
00855   char *FilterButtonSlotName;
00856 
00857   // Description:
00858   // Called when the number of presets has changed.
00859   // Note that the name of this function can be a bit misleading: if 
00860   // MaximumNumberOfPresets is set to a positive number, and the max
00861   // has been reached, this function will *still* be called twice, once
00862   // when the max is passed as a result of adding a preset, and then another
00863   // time when a preset is automatically deleted to get back to the maximum
00864   // value (which is, in most case, what you want to know anyway).
00865   virtual void NumberOfPresetsHasChanged();
00866 
00867   // Description:
00868   // Called when preset filtering has changed, i.e. a filter
00869   // constraint has been added/removed (see, ClearPresetFilter or
00870   // SetPresetFilterUserSlotConstraint).
00871   virtual void PresetFilteringHasChanged();
00872 
00873   // Description:
00874   // Called when preset filtering *may* have changed, the value of a slot has
00875   // changed and that slot was filtered (i.e. had a constraint put on it
00876   // using SetPresetFilterUserSlotConstraint), therefore it is possible that
00877   // preset maybe pass or not pass the filter anymore (IsPresetFiltered).
00878   virtual void PresetFilteringMayHaveChanged();
00879 
00880   // PIMPL Encapsulation for STL containers
00881   //BTX
00882   vtkKWPresetSelectorInternals *Internals;
00883   //ETX
00884 
00885   // Description:
00886   // Update all rows in the list
00887   virtual void UpdatePresetRows();
00888   virtual void ScheduleUpdatePresetRows();
00889   virtual void CancelScheduleUpdatePresetRows();
00890 
00891   char *PresetAddCommand;
00892   virtual int InvokePresetAddCommand();
00893 
00894   char *PresetUpdateCommand;
00895   virtual void InvokePresetUpdateCommand(int id);
00896 
00897   char *PresetApplyCommand;
00898   virtual void InvokePresetApplyCommand(int id);
00899 
00900   char *PresetRemoveCommand;
00901   virtual int InvokePresetRemoveCommand(int id);
00902 
00903   char *PresetRemovedCommand;
00904   virtual void InvokePresetRemovedCommand();
00905 
00906   char *PresetHasChangedCommand;
00907   virtual void InvokePresetHasChangedCommand(int id);
00908 
00909   char *PresetLoadCommand;
00910   virtual int InvokePresetLoadCommand();
00911 
00912   char *PresetFilteringHasChangedCommand;
00913   virtual void InvokePresetFilteringHasChangedCommand();
00914 
00915   char *CreateUserPresetButtonsCommand;
00916   virtual void InvokeCreateUserPresetButtonsCommand(vtkKWToolbar *, int);
00917 
00918   char *UpdateUserPresetButtonsCommand;
00919   virtual void InvokeUpdateUserPresetButtonsCommand(vtkKWToolbar *);
00920 
00921   char *SetUserPresetButtonsIconsCommand;
00922   virtual void InvokeSetUserPresetButtonsIconsCommand(vtkKWToolbar *);
00923 
00924   char *SetUserPresetButtonsHelpStringsCommand;
00925   virtual void InvokeSetUserPresetButtonsHelpStringsCommand(vtkKWToolbar *);
00926 
00927   // Description:
00928   // Get the index of a given column.
00929   virtual int GetIdColumnIndex();
00930   virtual int GetThumbnailColumnIndex();
00931   virtual int GetGroupColumnIndex();
00932   virtual int GetCommentColumnIndex();
00933 
00934   // Description:
00935   // Pack
00936   virtual void Pack();
00937 
00938   // Description:
00939   // Populate the pop-up context menu that is displayed when right-clicking
00940   // on a give preset. It should replicate the commands available through the
00941   // preset buttons.
00942   virtual void PopulatePresetContextMenu(vtkKWMenu *menu, int id);
00943 
00944   // Description:
00945   // Some constants
00946   //BTX
00947   static int SelectPreviousButtonId;
00948   static int SelectNextButtonId;
00949   static int AddButtonId;
00950   static int ApplyButtonId;
00951   static int UpdateButtonId;
00952   static int RemoveButtonId;
00953   static int LocateButtonId;
00954   static int EmailButtonId;
00955   static int LoadButtonId;
00956   static int FilterButtonId;
00957   //ETX
00958 
00959   // Description:
00960   // Access to the button label
00961   virtual const char* GetSelectPreviousButtonLabel();
00962   virtual const char* GetSelectNextButtonLabel();
00963   virtual const char* GetAddButtonLabel();
00964   virtual const char* GetApplyButtonLabel();
00965   virtual const char* GetUpdateButtonLabel();
00966   virtual const char* GetRemoveButtonLabel();
00967   virtual const char* GetRemoveAllButtonLabel();
00968   virtual const char* GetLocateButtonLabel();
00969   virtual const char* GetEmailButtonLabel();
00970   virtual const char* GetLoadButtonLabel();
00971   virtual const char* GetFilterButtonLabel();
00972   
00973   // Description:
00974   // Delete all presets, i.e. deallocate all presets and remove them
00975   // from the pool. Does not delete/remove any rows, see RemoveAllPresets()
00976   // to both delete all presets and update the table accordingly.
00977   // Return the number of presets deleted
00978   virtual int DeleteAllPresets();
00979 
00980   // Description:
00981   // Return the number of selected presets with filename
00982   virtual int GetNumberOfSelectedPresetsWithFileName();
00983 
00984   // Description:
00985   // Manage the preset Id to row index cache.
00986   virtual void SetPresetIdToRowIndexCacheEntry(int id, int row_index);
00987   virtual int GetPresetIdToRowIndexCacheEntry(int id);
00988   virtual void InvalidatePresetIdToRowIndexCache();
00989 
00990   // Description:
00991   // Manage the row index to preset Id cache.
00992   virtual void SetRowIndexToPresetIdCacheEntry(int row_index, int id);
00993   virtual int GetRowIndexToPresetIdCacheEntry(int row_index);
00994   virtual void InvalidateRowIndexToPresetIdCache();
00995 
00996   // Description:
00997   // Processes the events that are passed through CallbackCommand (or others).
00998   // Subclasses can oberride this method to process their own events, but
00999   // should call the superclass too.
01000   virtual void ProcessCallbackCommandEvents(
01001     vtkObject *caller, unsigned long event, void *calldata);
01002 
01003   // Description:
01004   // Constrain the number of presets (given MaximumNumberOfPresets).
01005   virtual void ConstrainNumberOfPresets();
01006   
01007   // Description:
01008   // Set the creation time of a preset.
01009   // Not a public method, but subclass may have a need to set it manually,
01010   // say if the presets are serialized to disk, one may want to load/bring 
01011   // them back with the same creation time as when they were first created.
01012   // Return 0 on error.
01013   virtual int SetPresetCreationTime(int id, vtkTypeInt64 value);
01014 
01015 private:
01016 
01017   vtkKWPresetSelector(const vtkKWPresetSelector&); // Not implemented
01018   void operator=(const vtkKWPresetSelector&); // Not implemented
01019 };
01020 
01021 #endif