interface/wx/propgrid/editors.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        editors.h
   3 // Purpose:     interface of wxPropertyGrid editors
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9
  10 /**
  11     @class wxPGEditor
  12
  13     Base class for custom wxPropertyGrid editors.
  14
  15     @remarks
  16     - Names of built-in property editors are: TextCtrl, Choice,
  17       ComboBox, CheckBox, TextCtrlAndButton, and ChoiceAndButton. Additional
  18       editors include SpinCtrl and DatePickerCtrl, but using them requires
  19       calling wxPropertyGrid::RegisterAdditionalEditors() prior use.
  20
  21     - Pointer to built-in editor is available as wxPGEditor_EditorName
  22       (eg. wxPGEditor_TextCtrl).
  23
  24     - Before you start using new editor you just created, you need to register
  25       it using static function
  26       wxPropertyGrid::RegisterEditorClass(), with code like this:
  27         @code
  28             wxPGEditor* editorPointer = wxPropertyGrid::RegisterEditorClass(new MyEditorClass(), "MyEditor");
  29         @endcode
  30       After that, wxPropertyGrid will take ownership of the given object, but
  31       you should still store editorPointer somewhere, so you can pass it to
  32       wxPGProperty::SetEditor(), or return it from wxPGEditor::DoGetEditorClass().
  33
  34     @library{wxpropgrid}
  35     @category{propgrid}
  36 */
  37 class wxPGEditor : public wxObject
  38 {
  39 public:
  40
  41     /** Constructor. */
  42     wxPGEditor();
  43
  44     /** Destructor. */
  45     virtual ~wxPGEditor();
  46
  47     /**
  48         Returns pointer to the name of the editor. For example,
  49         wxPGEditor_TextCtrl has name "TextCtrl". If you dont' need to access
  50         your custom editor by string name, then you do not need to implement
  51         this function.
  52     */
  53     virtual wxString GetName() const;
  54
  55     /**
  56         Instantiates editor controls.
  57
  58         @param propgrid
  59             wxPropertyGrid to which the property belongs (use as parent for control).
  60
  61         @param property
  62             Property for which this method is called.
  63
  64         @param pos
  65             Position, inside wxPropertyGrid, to create control(s) to.
  66
  67         @param size
  68             Initial size for control(s).
  69
  70         @remarks
  71         - Primary control shall use id wxPG_SUBID1, and secondary (button) control
  72           shall use wxPG_SUBID2.
  73         - Unlike in previous version of wxPropertyGrid, it is no longer
  74           necessary to call wxEvtHandler::Connect() for interesting editor
  75           events. Instead, all events from control are now automatically
  76           forwarded to wxPGEditor::OnEvent() and wxPGProperty::OnEvent().
  77     */
  78     virtual wxPGWindowList CreateControls( wxPropertyGrid* propgrid,
  79                                            wxPGProperty* property,
  80                                            const wxPoint& pos,
  81                                            const wxSize& size ) const = 0;
  82
  83     /** Loads value from property to the control. */
  84     virtual void UpdateControl( wxPGProperty* property, wxWindow* ctrl ) const = 0;
  85
  86     /**
  87         Draws value for given property.
  88     */
  89     virtual void DrawValue( wxDC& dc, const wxRect& rect,
  90                             wxPGProperty* property, const wxString& text ) const;
  91
  92     /**
  93         Handles events. Returns @true if value in control was modified
  94         (see wxPGProperty::OnEvent() for more information).
  95
  96         @remarks wxPropertyGrid will automatically unfocus the editor when
  97                  wxEVT_COMMAND_TEXT_ENTER is received and when it results in
  98                  property value being modified. This happens regardless of
  99                  editor type (ie. behavior is same for any wxTextCtrl and
 100                  wxComboBox based editor).
 101     */
 102     virtual bool OnEvent( wxPropertyGrid* propgrid, wxPGProperty* property,
 103         wxWindow* wnd_primary, wxEvent& event ) const = 0;
 104
 105     /**
 106         Returns value from control, via parameter 'variant'.
 107         Usually ends up calling property's StringToValue() or IntToValue().
 108         Returns @true if value was different.
 109     */
 110     virtual bool GetValueFromControl( wxVariant& variant, wxPGProperty* property,
 111                                       wxWindow* ctrl ) const;
 112
 113     /** Sets value in control to unspecified. */
 114     virtual void SetValueToUnspecified( wxPGProperty* property,
 115                                         wxWindow* ctrl ) const = 0;
 116
 117     /**
 118         Called by property grid to set new appearance for the control.
 119         Default implementation  sets foreground colour, background colour,
 120         font, plus text for wxTextCtrl and wxComboCtrl.
 121
 122         The parameter @a appearance represents the new appearance to be applied.
 123
 124         The parameter @a oldAppearance is the previously applied appearance.
 125         Used to detect which control attributes need to be changed (e.g. so we only
 126         change background colour if really needed).
 127
 128         Finally, the parameter @a unspecified if @true tells this function that
 129         the new appearance represents an unspecified property value.
 130     */
 131     virtual void SetControlAppearance( wxPropertyGrid* pg,
 132                                        wxPGProperty* property,
 133                                        wxWindow* ctrl,
 134                                        const wxPGCell& appearance,
 135                                        const wxPGCell& oldAppearance,
 136                                        bool unspecified ) const;
 137
 138     /** Sets control's value specifically from string. */
 139     virtual void SetControlStringValue( wxPGProperty* property,
 140                                         wxWindow* ctrl, const wxString& txt ) const;
 141
 142     /** Sets control's value specifically from int (applies to choice etc.). */
 143     virtual void SetControlIntValue( wxPGProperty* property,
 144                                      wxWindow* ctrl, int value ) const;
 145
 146     /**
 147         Inserts item to existing control. Index -1 means end of list.
 148         Default implementation does nothing. Returns index of item added.
 149     */
 150     virtual int InsertItem( wxWindow* ctrl, const wxString& label, int index ) const;
 151
 152     /**
 153         Deletes item from existing control.
 154         Default implementation does nothing.
 155     */
 156     virtual void DeleteItem( wxWindow* ctrl, int index ) const;
 157
 158     /**
 159         Extra processing when control gains focus.
 160         For example, wxTextCtrl based controls should select all text.
 161     */
 162     virtual void OnFocus( wxPGProperty* property, wxWindow* wnd ) const;
 163
 164     /**
 165         Returns @true if control itself can contain the custom image.
 166         Default implementation returns @false.
 167     */
 168     virtual bool CanContainCustomImage() const;
 169 };
 170
 171
 172
 173 /**
 174     @class wxPGMultiButton
 175
 176     This class can be used to have multiple buttons in a property editor.
 177     You will need to create a new property editor class, override CreateControls,
 178     and have it return wxPGMultiButton instance in wxPGWindowList::SetSecondary().
 179
 180     For instance, here we add three buttons to a TextCtrl editor:
 181
 182     @code
 183     #include <wx/propgrid/editors.h>
 184
 185     class wxSampleMultiButtonEditor : public wxPGTextCtrlEditor
 186     {
 187         DECLARE_DYNAMIC_CLASS(wxSampleMultiButtonEditor)
 188     public:
 189         wxSampleMultiButtonEditor() {}
 190         virtual ~wxSampleMultiButtonEditor() {}
 191
 192         virtual wxString GetName() const { return "SampleMultiButtonEditor"; }
 193
 194         virtual wxPGWindowList CreateControls( wxPropertyGrid* propGrid,
 195                                                wxPGProperty* property,
 196                                                const wxPoint& pos,
 197                                                const wxSize& sz ) const;
 198         virtual bool OnEvent( wxPropertyGrid* propGrid,
 199                               wxPGProperty* property,
 200                               wxWindow* ctrl,
 201                               wxEvent& event ) const;
 202     };
 203
 204     IMPLEMENT_DYNAMIC_CLASS(wxSampleMultiButtonEditor, wxPGTextCtrlEditor)
 205
 206     wxPGWindowList wxSampleMultiButtonEditor::CreateControls( wxPropertyGrid* propGrid,
 207                                                               wxPGProperty* property,
 208                                                               const wxPoint& pos,
 209                                                               const wxSize& sz ) const
 210     {
 211         // Create and populate buttons-subwindow
 212         wxPGMultiButton* buttons = new wxPGMultiButton( propGrid, sz );
 213
 214         // Add two regular buttons
 215         buttons->Add( "..." );
 216         buttons->Add( "A" );
 217         // Add a bitmap button
 218         buttons->Add( wxArtProvider::GetBitmap(wxART_FOLDER) );
 219
 220         // Create the 'primary' editor control (textctrl in this case)
 221         wxPGWindowList wndList = wxPGTextCtrlEditor::CreateControls
 222                                  ( propGrid, property, pos,
 223                                    buttons->GetPrimarySize() );
 224
 225         // Finally, move buttons-subwindow to correct position and make sure
 226         // returned wxPGWindowList contains our custom button list.
 227         buttons->Finalize(propGrid, pos);
 228
 229         wndList.SetSecondary( buttons );
 230         return wndList;
 231     }
 232
 233     bool wxSampleMultiButtonEditor::OnEvent( wxPropertyGrid* propGrid,
 234                                              wxPGProperty* property,
 235                                              wxWindow* ctrl,
 236                                              wxEvent& event ) const
 237     {
 238         if ( event.GetEventType() == wxEVT_COMMAND_BUTTON_CLICKED )
 239         {
 240             wxPGMultiButton* buttons = (wxPGMultiButton*) propGrid->GetEditorControlSecondary();
 241
 242             if ( event.GetId() == buttons->GetButtonId(0) )
 243             {
 244                 // Do something when the first button is pressed
 245                 // Return true if the action modified the value in editor.
 246                 ...
 247             }
 248             if ( event.GetId() == buttons->GetButtonId(1) )
 249             {
 250                 // Do something when the second button is pressed
 251                 ...
 252             }
 253             if ( event.GetId() == buttons->GetButtonId(2) )
 254             {
 255                 // Do something when the third button is pressed
 256                 ...
 257             }
 258         }
 259         return wxPGTextCtrlEditor::OnEvent(propGrid, property, ctrl, event);
 260     }
 261     @endcode
 262
 263     Further to use this editor, code like this can be used:
 264
 265     @code
 266         // Register editor class - needs only to be called once
 267         wxPGEditor* multiButtonEditor = new wxSampleMultiButtonEditor();
 268         wxPropertyGrid::RegisterEditorClass( multiButtonEditor );
 269
 270         // Insert the property that will have multiple buttons
 271         propGrid->Append( new wxLongStringProperty("MultipleButtons", wxPG_LABEL) );
 272
 273         // Change property to use editor created in the previous code segment
 274         propGrid->SetPropertyEditor( "MultipleButtons", multiButtonEditor );
 275     @endcode
 276
 277     @library{wxpropgrid}
 278     @category{propgrid}
 279 */
 280 class WXDLLIMPEXP_PROPGRID wxPGMultiButton : public wxWindow
 281 {
 282 public:
 283     /**
 284         Constructor.
 285     */
 286     wxPGMultiButton( wxPropertyGrid* pg, const wxSize& sz );
 287
 288     /**
 289         Destructor.
 290     */
 291     virtual ~wxPGMultiButton() { }
 292
 293     /**
 294         Adds new button, with given label.
 295     */
 296     void Add( const wxString& label, int id = -2 );
 297
 298     /**
 299         Adds new bitmap button.
 300     */
 301     void Add( const wxBitmap& bitmap, int id = -2 );
 302
 303     /**
 304         Call this in CreateControls() of your custom editor class
 305         after all buttons have been added.
 306
 307         @param propGrid
 308             wxPropertyGrid given in CreateControls().
 309
 310         @param pos
 311             wxPoint given in CreateControls().
 312     */
 313     void Finalize( wxPropertyGrid* propGrid, const wxPoint& pos );
 314
 315     /**
 316         Returns pointer to one of the buttons.
 317     */
 318     wxWindow* GetButton( unsigned int i );
 319
 320     /**
 321         Returns Id of one of the buttons.
 322         This is utility function to be used in event handlers.
 323     */
 324     int GetButtonId( unsigned int i ) const;
 325
 326     /**
 327         Returns number of buttons.
 328     */
 329     unsigned int GetCount();
 330
 331     /**
 332         Returns size of primary editor control, as appropriately
 333         reduced by number of buttons present.
 334     */
 335     wxSize GetPrimarySize() const;
 336 };
 337