KWWidgets
vtkKWMostRecentFilesManager.h
Go to the documentation of this file.
00001 /*=========================================================================
00002 
00003   Module:    $RCSfile: vtkKWMostRecentFilesManager.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 vtkKWMostRecentFilesManager - a "most recent files" manager.
00015 // .SECTION Description
00016 // This class is basically a manager that acts as a container for a set of
00017 // most recent files.
00018 // It provides methods to manipulate them, load/save them from/to the
00019 // registry, and display them as entries in a menu.
00020 // An instance of this class is created in vtkKWWindowBase
00021 // .SECTION Thanks
00022 // This work is part of the National Alliance for Medical Image
00023 // Computing (NAMIC), funded by the National Institutes of Health
00024 // through the NIH Roadmap for Medical Research, Grant U54 EB005149.
00025 // Information on the National Centers for Biomedical Computing
00026 // can be obtained from http://nihroadmap.nih.gov/bioinformatics.
00027 // .SECTION See Also
00028 // vtkKWWindowBase
00029 
00030 #ifndef __vtkKWMostRecentFilesManager_h
00031 #define __vtkKWMostRecentFilesManager_h
00032 
00033 #include "vtkKWObject.h"
00034 
00035 class vtkKWMostRecentFilesManagerInternals;
00036 class vtkKWMenu;
00037 
00038 class KWWidgets_EXPORT vtkKWMostRecentFilesManager : public vtkKWObject
00039 {
00040 public:
00041   static vtkKWMostRecentFilesManager* New();
00042   vtkTypeRevisionMacro(vtkKWMostRecentFilesManager,vtkKWObject);
00043   void PrintSelf(ostream& os, vtkIndent indent);
00044 
00045   // Description:
00046   // Add a most recent file to the list.
00047   // Each most recent file is associated to a target object and a target 
00048   // command: when a most recent file is invoked (either programmatically or
00049   // using the most recent files menu), the associated target commmand is 
00050   // invoked on the associated target object. If one and/or the other was not
00051   // specified when the most recent file was added, the default target
00052   // object and/or default target command are used.
00053   // An optional label can be specified too.
00054   // This label will be used in the menu if LabelVisibilityInMenu is true.
00055   // The entry is always added at the beginning of the list (thus, becoming
00056   // the most recently used).
00057   virtual void AddFile(
00058     const char *filename, 
00059     vtkObject *target_object = NULL, 
00060     const char *target_command = NULL,
00061     const char *label = NULL);
00062   
00063   // Description:
00064   // Query the files
00065   virtual int GetNumberOfFiles();
00066   virtual const char* GetNthFileName(int idx);
00067   virtual vtkObject* GetNthTargetObject(int idx);
00068   virtual const char* GetNthTargetCommand(int idx);
00069   virtual const char* GetNthLabel(int idx);
00070 
00071   // Description:
00072   // Set/Get the default target object and command.
00073   // Each most recent file is associated to a target object and a target 
00074   // command: when a most recent file is invoked (either programmatically or
00075   // using the most recent files menu), the associated target commmand is 
00076   // invoked on the associated target object. If one and/or the other was not
00077   // specified when the most recent file was added, the default target
00078   // object and default target command are used.
00079   vtkGetObjectMacro(DefaultTargetObject, vtkObject);
00080   virtual void SetDefaultTargetObject(vtkObject *object);
00081   vtkGetStringMacro(DefaultTargetCommand);
00082   virtual void SetDefaultTargetCommand(const char *);
00083 
00084   // Description:
00085   // Load/Save up to 'max_nb' most recent files from/to the registry under
00086   // the application's 'reg_key' key.
00087   // The parameter-less methods use RegistryKey as 'reg_key' and
00088   // MaximumNumberOfFilesInRegistry as 'max_nb'.
00089   // Only the filename and target command are saved. When entries are loaded
00090   // make sure DefaultTargetObject is set to a valid object.
00091   virtual void RestoreFilesListFromRegistry();
00092   virtual void SaveFilesToRegistry();
00093   virtual void RestoreFilesListFromRegistry(
00094     const char *reg_key, int max_nb);
00095   virtual void SaveFilesToRegistry(
00096     const char *reg_key, int max_nb);
00097 
00098   // Description:
00099   // Set/Get the default registry key the most recent files are saved to or
00100   // loaded from when it is not specified explicitly while calling load/save.
00101   vtkGetStringMacro(RegistryKey);
00102   vtkSetStringMacro(RegistryKey);
00103 
00104   // Description:
00105   // Set/Get the default maximum number of recent files in the registry when
00106   // this number is not specified explicitly while calling load/save.
00107   vtkGetMacro(MaximumNumberOfFilesInRegistry, int);
00108   vtkSetMacro(MaximumNumberOfFilesInRegistry, int);
00109 
00110   // Description:
00111   // Get a most recent files menu object. 
00112   // This menu is updated automatically as entries are added and removed,
00113   // up to MaximumNumberOfFilesInMenu entries.
00114   // It is up to the caller to set its parent, and it should be done as soon as
00115   // possible if there is a need to use this menu.
00116   vtkKWMenu* GetMenu();
00117 
00118   // Description:
00119   // Set/Get the maximum number of recent files in the internal most recent
00120   // files menu object (see GetMenu()).
00121   vtkGetMacro(MaximumNumberOfFilesInMenu, int);
00122   virtual void SetMaximumNumberOfFilesInMenu(int);
00123 
00124   // Description:
00125   // Set a label for a specific file entry.
00126   // This label will be used in the menu if LabelVisibilityInMenu is true.
00127   virtual void SetFileLabel(const char *filename, const char *label);
00128 
00129   // Description:
00130   // Set/Get the label visibility in menu (Off by default).
00131   virtual void SetLabelVisibilityInMenu(int);
00132   vtkBooleanMacro(LabelVisibilityInMenu, int);
00133   vtkGetMacro(LabelVisibilityInMenu, int);
00134 
00135   // Description:
00136   // Set/Get the basename visibility in menu (On by default).
00137   // (i.e., instead of "d:/temp/foo.raw", display "d:/temp")
00138   // This setting is ignored per entry if no label is found for that specific
00139   // menu entry (in which case only a directory would be displayed, which makes
00140   // poor sense).
00141   virtual void SetBaseNameVisibilityInMenu(int);
00142   vtkBooleanMacro(BaseNameVisibilityInMenu, int);
00143   vtkGetMacro(BaseNameVisibilityInMenu, int);
00144 
00145   // Description:
00146   // Separate path from basename in menu (Off by default).
00147   // (i.e., instead of "d:/temp/foo.raw", display "foo.raw in d:/temp")
00148   virtual void SetSeparatePathInMenu(int);
00149   vtkBooleanMacro(SeparatePathInMenu, int);
00150   vtkGetMacro(SeparatePathInMenu, int);
00151 
00152   // Description:
00153   // Disable/Enable the most recent files menu if it is a cascade in its
00154   // parent. If the menu is empty, it will be disabled.
00155   virtual void UpdateMenuStateInParent();
00156 
00157   // Description:
00158   // Populate a given menu with up to 'max_nb' most recent files entries.
00159   // You do not need to call this method on GetMenu(), the
00160   // internal menu is updated automatically.
00161   virtual void PopulateMenu(vtkKWMenu*, int max_nb);
00162 
00163   // Description:
00164   // Event list
00165   //BTX
00166   enum
00167   {
00168     MenuHasChangedEvent = 24000
00169   };
00170   //ETX
00171 
00172 protected:
00173   vtkKWMostRecentFilesManager();
00174   ~vtkKWMostRecentFilesManager();
00175 
00176   char        *DefaultTargetCommand;
00177   vtkObject   *DefaultTargetObject;
00178   char        *RegistryKey;
00179   int         MaximumNumberOfFilesInRegistry;
00180   int         MaximumNumberOfFilesInMenu;
00181   int         LabelVisibilityInMenu;
00182   int         BaseNameVisibilityInMenu;
00183   int         SeparatePathInMenu;
00184 
00185   //BTX
00186 
00187   // PIMPL Encapsulation for STL containers
00188 
00189   vtkKWMostRecentFilesManagerInternals *Internals;
00190   friend class vtkKWMostRecentFilesManagerInternals;
00191 
00192   //ETX
00193 
00194   // Description:
00195   // Add a most recent file to the list (internal, do not update the menu
00196   // or save to the registry).
00197   virtual void AddFileInternal(
00198     const char *filename, 
00199     vtkObject *target_object = NULL, 
00200     const char *target_command = NULL,
00201     const char *label = NULL);
00202 
00203   // Description:
00204   // Update the most recent files menu
00205   virtual void UpdateMenu();
00206 
00207 private:
00208   
00209   // In private for lazy allocation using GetMenu()
00210 
00211   vtkKWMenu *Menu;
00212 
00213   vtkKWMostRecentFilesManager(const vtkKWMostRecentFilesManager&); // Not implemented
00214   void operator=(const vtkKWMostRecentFilesManager&); // Not implemented
00215 };
00216 
00217 #endif
00218