KWWidgets
|
00001 /*========================================================================= 00002 00003 Module: $RCSfile: vtkKWScaleWithEntry.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 vtkKWScaleWithEntry - a scale widget with a label and entry 00015 // .SECTION Description 00016 // A widget that represents a more complex scale (or slider) with options for 00017 // positioning a label, displaying an entry, working in popup mode, etc. 00018 // For a more lightweight widget, check vtkKWScale. 00019 // The label position and visibility can be changed through the 00020 // vtkKWWidgetWithLabel superclass methods (see SetLabelPosition). 00021 // The default position for the label is on the left of the scale for 00022 // horizontal scales, on the right (top corner) for vertical ones. 00023 // The default position for the entry is on the right of the scale for 00024 // horizontal scales, on the right (bottom corner) for vertical ones. 00025 // Both label and entry are visible by default. 00026 // For convenience purposes, an empty label is not displayed though (make 00027 // sure you use the SetLabelText method to set the label). 00028 // In popup mode, a small button replaces the scale. Pressing that button 00029 // will popup a scale the user can interact with, until it leaves the scale 00030 // focus, which will withdraw the popup automatically. In that mode, the 00031 // label and entry position are always displayed side by side, horizontally. 00032 // Many of the vtkKWScale methods have been added to this API for 00033 // convenience purposes, but GetScale() can be used to retrieve the 00034 // internal vtkKWScale and access the rest of the API. 00035 // .SECTION See Also 00036 // vtkKWScale vtkKWScaleWithLabel vtkKWWidgetWithLabel 00037 00038 #ifndef __vtkKWScaleWithEntry_h 00039 #define __vtkKWScaleWithEntry_h 00040 00041 #include "vtkKWScaleWithLabel.h" 00042 00043 class vtkKWEntry; 00044 class vtkKWLabel; 00045 class vtkKWPushButton; 00046 class vtkKWTopLevel; 00047 00048 class KWWidgets_EXPORT vtkKWScaleWithEntry : public vtkKWScaleWithLabel 00049 { 00050 public: 00051 static vtkKWScaleWithEntry* New(); 00052 vtkTypeRevisionMacro(vtkKWScaleWithEntry,vtkKWScaleWithLabel); 00053 void PrintSelf(ostream& os, vtkIndent indent); 00054 00055 // Description: 00056 // Set the range for this scale. 00057 virtual void SetRange(double min, double max); 00058 virtual void SetRange(const double *range) 00059 { this->SetRange(range[0], range[1]); }; 00060 virtual double *GetRange(); 00061 virtual void GetRange(double &min, double &max); 00062 virtual void GetRange(double range[2]) 00063 { this->GetRange(range[0], range[1]); }; 00064 virtual double GetRangeMin() { return this->GetRange()[0]; }; 00065 virtual double GetRangeMax() { return this->GetRange()[1]; }; 00066 00067 // Description: 00068 // Set/Get the value of the scale. 00069 virtual void SetValue(double v); 00070 virtual double GetValue(); 00071 00072 // Description: 00073 // Set/Get the resolution of the slider. 00074 virtual void SetResolution(double r); 00075 virtual double GetResolution(); 00076 00077 // Description: 00078 // Turn on/off the automatic clamping of the end values when the 00079 // user types a value beyond the range. Default is on. 00080 virtual void SetClampValue(int); 00081 virtual int GetClampValue(); 00082 vtkBooleanMacro(ClampValue, int); 00083 00084 // Description: 00085 // Get the internal vtkKWScale. 00086 // Retrive that object to set the resolution, range, value, etc. 00087 virtual vtkKWScale* GetScale() 00088 { return this->GetWidget(); }; 00089 00090 // Description: 00091 // Set/Get whether to display the range of the scale. 00092 // If the scale orientation is horizontal, the min is displayed on the 00093 // left of the scale, the max range on the right. For vertical orientation, 00094 // min is on top, max at the bottom. In popup mode, the range is 00095 // displayed directly in the popup window using the same layout as above. 00096 void SetRangeVisibility(int flag); 00097 vtkGetMacro(RangeVisibility, int); 00098 vtkBooleanMacro(RangeVisibility, int); 00099 00100 // Description: 00101 // Set/Get the internal entry visibility (On by default). 00102 // IMPORTANT: if you know you may not show the entry, try to 00103 // set that flag as early as possible (ideally, before calling Create()) 00104 // in order to lower the footprint of the widget: the entry will not be 00105 // allocated and created if there is no need to show it. 00106 // Later on, you can still use that option to show the entry: it will be 00107 // allocated and created on the fly. 00108 virtual void SetEntryVisibility(int); 00109 vtkBooleanMacro(EntryVisibility, int); 00110 vtkGetMacro(EntryVisibility, int); 00111 00112 // Description: 00113 // Set the contents label. 00114 // IMPORTANT: this method will create the label on the fly, use it only if 00115 // you are confident that you will indeed display the label. 00116 // Override the superclass so that the label is packed/unpacked if the 00117 // text value is an empty string. 00118 virtual void SetLabelText(const char *); 00119 00120 // Description: 00121 // Get the internal entry. 00122 // IMPORTANT: the internal entry is "lazy created", i.e. it is neither 00123 // allocated nor created until GetEntry() is called. This allows 00124 // for a lower footprint and faster UI startup. Therefore, do *not* use 00125 // GetEntry() to check if the entry exists, as it will automatically 00126 // allocate the entry. Use HasEntry() instead. 00127 virtual vtkKWEntry* GetEntry(); 00128 virtual int HasEntry(); 00129 00130 // Description: 00131 // Set/Get the entry width. 00132 // IMPORTANT: this method will create the entry on the fly, use it only if 00133 // you are confident that you will indeed display the entry. 00134 virtual void SetEntryWidth(int width); 00135 virtual int GetEntryWidth(); 00136 00137 // Description: 00138 // If supported, set the entry position in regards to the rest of 00139 // the composite widget. Check the subclass for more information about 00140 // what the Default position is, and if specific positions are supported. 00141 // The default position for the entry is on the right of the scale for 00142 // horizontal scales, on the right (bottom corner) for vertical ones. 00143 // Remember that the label position and visibility can also be changed 00144 // through the vtkKWWidgetWithLabel superclass methods (SetLabelPosition). 00145 //BTX 00146 enum 00147 { 00148 EntryPositionDefault = 0, 00149 EntryPositionTop, 00150 EntryPositionBottom, 00151 EntryPositionLeft, 00152 EntryPositionRight 00153 }; 00154 //ETX 00155 virtual void SetEntryPosition(int); 00156 vtkGetMacro(EntryPosition, int); 00157 virtual void SetEntryPositionToDefault() 00158 { this->SetEntryPosition(vtkKWScaleWithEntry::EntryPositionDefault); }; 00159 virtual void SetEntryPositionToTop() 00160 { this->SetEntryPosition(vtkKWScaleWithEntry::EntryPositionTop); }; 00161 virtual void SetEntryPositionToBottom() 00162 { this->SetEntryPosition(vtkKWScaleWithEntry::EntryPositionBottom); }; 00163 virtual void SetEntryPositionToLeft() 00164 { this->SetEntryPosition(vtkKWScaleWithEntry::EntryPositionLeft); }; 00165 virtual void SetEntryPositionToRight() 00166 { this->SetEntryPosition(vtkKWScaleWithEntry::EntryPositionRight); }; 00167 00168 // Description: 00169 // Set both the label and entry position to the top of the scale 00170 // (label in the left corner, entry in the right corner) 00171 virtual void SetLabelAndEntryPositionToTop(); 00172 00173 // Description: 00174 // Set/Get a popup scale. 00175 // WARNING: must be set *before* Create() is called. 00176 vtkSetMacro(PopupMode, int); 00177 vtkGetMacro(PopupMode, int); 00178 vtkBooleanMacro(PopupMode, int); 00179 vtkGetObjectMacro(PopupPushButton, vtkKWPushButton); 00180 00181 // Description: 00182 // Set/Get the entry expansion flag. This flag is only used if PopupMode 00183 // mode is On. In that case, the default behaviour is to provide a widget 00184 // as compact as possible, i.e. the Entry won't be expanded if the widget 00185 // grows. Set ExpandEntry to On to override this behaviour. 00186 virtual void SetExpandEntry(int flag); 00187 vtkGetMacro(ExpandEntry, int); 00188 vtkBooleanMacro(ExpandEntry, int); 00189 00190 // Description: 00191 // Set/Get the orientation type. 00192 // For widgets that can lay themselves out with either a horizontal or 00193 // vertical orientation, such as scales, this option specifies which 00194 // orientation should be used. 00195 // Valid constants can be found in vtkKWOptions::OrientationType. 00196 virtual void SetOrientation(int); 00197 virtual int GetOrientation(); 00198 virtual void SetOrientationToHorizontal(); 00199 virtual void SetOrientationToVertical(); 00200 00201 // Description 00202 // Set/Get the desired long dimension of the scale. 00203 // For vertical scales this is the scale's height, for horizontal scales 00204 // it is the scale's width. In pixel. 00205 virtual void SetLength(int length); 00206 virtual int GetLength(); 00207 00208 // Description: 00209 // Specifies commands to associate with the widget. 00210 // 'Command' is invoked when the widget value is changing (i.e. during 00211 // user interaction). 00212 // 'StartCommand' is invoked at the beginning of a user interaction with 00213 // the widget (when a mouse button is pressed over the widget for example). 00214 // 'EndCommand' is invoked at the end of the user interaction with the 00215 // widget (when the mouse button is released for example). 00216 // 'EntryCommand' is invoked when the widget value is changed using 00217 // the text entry. 00218 // The need for a 'Command', 'StartCommand' and 'EndCommand' can be 00219 // explained as follows: 'EndCommand' can be used to be notified about any 00220 // changes made to this widget *after* the corresponding user interaction has 00221 // been performed (say, after releasing the mouse button that was dragging 00222 // a slider, or after clicking on a checkbutton). 'Command' can be set 00223 // *additionally* to be notified about the intermediate changes that 00224 // occur *during* the corresponding user interaction (say, *while* dragging 00225 // a slider). While setting 'EndCommand' is enough to be notified about 00226 // any changes, setting 'Command' is an application-specific choice that 00227 // is likely to depend on how fast you want (or can) answer to rapid changes 00228 // occuring during a user interaction, if any. 'StartCommand' is rarely 00229 // used but provides an opportunity for the application to modify its 00230 // state and prepare itself for user-interaction; in that case, the 00231 // 'EndCommand' is usually set in a symmetric fashion to set the application 00232 // back to its previous state. 00233 // The 'object' argument is the object that will have the method called on 00234 // it. The 'method' argument is the name of the method to be called and any 00235 // arguments in string form. If the object is NULL, the method is still 00236 // evaluated as a simple command. 00237 // Note that the same events as vtkKWScale are generated, as a convenience. 00238 // The following parameters are also passed to the command: 00239 // - the current value: double 00240 virtual void SetCommand(vtkObject *object, const char *method); 00241 virtual void SetStartCommand(vtkObject *object, const char *method); 00242 virtual void SetEndCommand(vtkObject *object, const char *method); 00243 virtual void SetEntryCommand(vtkObject *object, const char *method); 00244 00245 // Description: 00246 // Events. IMPORTANT: this widget is a composite widget that assembles 00247 // both a vtkKWScale (which can be retrieved using GetScale()) and a 00248 // (which can be retrieved using GetEntry()). Events are generated by 00249 // both classes separately (see the corresponding class documentation). 00250 // HOWEVER, for convenience purposes, an instance of vtkKWScaleWithEntry 00251 // will emit (i.e. forward) the events that were sent by its internal 00252 // vtkKWScale automatically, just as if they were sent by the instance 00253 // itself. Therefore, you do not need to listen to the internal GetScale() 00254 // or GetEntry() objects, but to the instance directly. 00255 // Check the vtkKWScale documentation for the list of events. 00256 // (for example, vtkKWScale::ScaleValueChangingEvent, 00257 // vtkKWScale::ScaleValueChangedEvent, 00258 // vtkKWScale::ScaleValueStartChangingEvent, etc). 00259 00260 // Description: 00261 // Set/Get whether the above commands should be called or not. 00262 // This make it easier to disable the commands while setting the scale 00263 // value for example. 00264 virtual void SetDisableCommands(int); 00265 virtual int GetDisableCommands(); 00266 vtkBooleanMacro(DisableCommands, int); 00267 00268 // Description: 00269 // Setting this string enables balloon help for this widget. 00270 // Override to pass down to children for cleaner behavior 00271 virtual void SetBalloonHelpString(const char *str); 00272 00273 // Description: 00274 // Update the "enable" state of the object and its internal parts. 00275 // Depending on different Ivars (this->Enabled, the application's 00276 // Limited Edition Mode, etc.), the "enable" state of the object is updated 00277 // and propagated to its internal parts/subwidgets. This will, for example, 00278 // enable/disable parts of the widget UI, enable/disable the visibility 00279 // of 3D widgets, etc. 00280 virtual void UpdateEnableState(); 00281 00282 // Description: 00283 // Callbacks. Internal, do not use. 00284 virtual void DisplayPopupModeCallback(); 00285 virtual void WithdrawPopupModeCallback(); 00286 virtual void EntryValueCallback(const char *value); 00287 virtual void ScaleValueCallback(double num); 00288 00289 // Description: 00290 // Add all the default observers needed by that object, or remove 00291 // all the observers that were added through AddCallbackCommandObserver. 00292 // Subclasses can override these methods to add/remove their own default 00293 // observers, but should call the superclass too. 00294 virtual void AddCallbackCommandObservers(); 00295 virtual void RemoveCallbackCommandObservers(); 00296 00297 protected: 00298 vtkKWScaleWithEntry(); 00299 ~vtkKWScaleWithEntry(); 00300 00301 // Description: 00302 // Create the widget. 00303 virtual void CreateWidget(); 00304 00305 // Description: 00306 // Bind/Unbind all components so that values can be changed, but 00307 // no command will be called. 00308 void Bind(); 00309 void UnBind(); 00310 00311 int PopupMode; 00312 int RangeVisibility; 00313 00314 virtual void InvokeEntryCommand(double value); 00315 char *EntryCommand; 00316 00317 int EntryVisibility; 00318 int EntryPosition; 00319 int ExpandEntry; 00320 00321 vtkKWTopLevel *TopLevel; 00322 vtkKWPushButton *PopupPushButton; 00323 00324 vtkKWLabel *RangeMinLabel; 00325 vtkKWLabel *RangeMaxLabel; 00326 00327 // Description: 00328 // Pack or repack the widget. To be implemented by subclasses. 00329 virtual void Pack(); 00330 00331 // Description: 00332 // Create the entry 00333 virtual void CreateEntry(); 00334 00335 // Description: 00336 // Update internal widgets value 00337 virtual void UpdateValue(); 00338 virtual void SetEntryValue(double num); 00339 virtual void UpdateRange(); 00340 00341 // Description: 00342 // Processes the events that are passed through CallbackCommand (or others). 00343 // Subclasses can oberride this method to process their own events, but 00344 // should call the superclass too. 00345 virtual void ProcessCallbackCommandEvents( 00346 vtkObject *caller, unsigned long event, void *calldata); 00347 00348 private: 00349 00350 // Description: 00351 // Internal entry 00352 // In 'private:' to allow lazy evaluation. GetEntry() will create the 00353 // entry if it does not exist. This allow the object to remain lightweight. 00354 vtkKWEntry *Entry; 00355 00356 vtkKWScaleWithEntry(const vtkKWScaleWithEntry&); // Not implemented 00357 void operator=(const vtkKWScaleWithEntry&); // Not implemented 00358 }; 00359 00360 00361 #endif 00362 00363 00364