interface/wx/propgrid/editors.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        editors.h
   3 // Purpose:     interface of wxPropertyGrid editors
   4 // Author:      wxWidgets team
   5 // Licence:     wxWindows licence
   6 /////////////////////////////////////////////////////////////////////////////
   7
   8
   9 /**
  10     @class wxPGEditor
  11
  12     Base class for custom wxPropertyGrid editors.
  13
  14     @remarks
  15     - Names of built-in property editors are: TextCtrl, Choice,
  16       ComboBox, CheckBox, TextCtrlAndButton, and ChoiceAndButton. Additional
  17       editors include SpinCtrl and DatePickerCtrl, but using them requires
  18       calling wxPropertyGrid::RegisterAdditionalEditors() prior use.
  19
  20     - Pointer to built-in editor is available as wxPGEditor_EditorName
  21       (eg. wxPGEditor_TextCtrl).
  22
  23     - Before you start using new editor you just created, you need to register
  24       it using static function
  25       wxPropertyGrid::RegisterEditorClass(), with code like this:
  26         @code
  27             wxPGEditor* editorPointer = wxPropertyGrid::RegisterEditorClass(new MyEditorClass(), "MyEditor");
  28         @endcode
  29       After that, wxPropertyGrid will take ownership of the given object, but
  30       you should still store editorPointer somewhere, so you can pass it to
  31       wxPGProperty::SetEditor(), or return it from wxPGEditor::DoGetEditorClass().
  32
  33     @library{wxpropgrid}
  34     @category{propgrid}
  35 */
  36 class wxPGEditor : public wxObject
  37 {
  38 public:
  39
  40     /** Constructor. */
  41     wxPGEditor();
  42
  43     /** Destructor. */
  44     virtual ~wxPGEditor();
  45
  46     /**
  47         Returns pointer to the name of the editor. For example,
  48         wxPGEditor_TextCtrl has name "TextCtrl". If you dont' need to access
  49         your custom editor by string name, then you do not need to implement
  50         this function.
  51     */
  52     virtual wxString GetName() const;
  53
  54     /**
  55         Instantiates editor controls.
  56
  57         @param propgrid
  58             wxPropertyGrid to which the property belongs (use as parent for control).
  59
  60         @param property
  61             Property for which this method is called.
  62
  63         @param pos
  64             Position, inside wxPropertyGrid, to create control(s) to.
  65
  66         @param size
  67             Initial size for control(s).
  68
  69         @remarks
  70         - Primary control shall use id wxPG_SUBID1, and secondary (button) control
  71           shall use wxPG_SUBID2.
  72         - Unlike in previous version of wxPropertyGrid, it is no longer
  73           necessary to call wxEvtHandler::Connect() for interesting editor
  74           events. Instead, all events from control are now automatically
  75           forwarded to wxPGEditor::OnEvent() and wxPGProperty::OnEvent().
  76     */
  77     virtual wxPGWindowList CreateControls( wxPropertyGrid* propgrid,
  78                                            wxPGProperty* property,
  79                                            const wxPoint& pos,
  80                                            const wxSize& size ) const = 0;
  81
  82     /** Loads value from property to the control. */
  83     virtual void UpdateControl( wxPGProperty* property, wxWindow* ctrl ) const = 0;
  84
  85     /**
  86         Draws value for given property.
  87     */
  88     virtual void DrawValue( wxDC& dc, const wxRect& rect,
  89                             wxPGProperty* property, const wxString& text ) const;
  90
  91     /**
  92         Handles events. Returns @true if value in control was modified
  93         (see wxPGProperty::OnEvent() for more information).
  94
  95         @remarks wxPropertyGrid will automatically unfocus the editor when
  96                  @c wxEVT_TEXT_ENTER is received and when it results in
  97                  property value being modified. This happens regardless of
  98                  editor type (ie. behaviour is same for any wxTextCtrl and
  99                  wxComboBox based editor).
 100     */
 101     virtual bool OnEvent( wxPropertyGrid* propgrid, wxPGProperty* property,
 102         wxWindow* wnd_primary, wxEvent& event ) const = 0;
 103
 104     /**
 105         Returns value from control, via parameter 'variant'.
 106         Usually ends up calling property's StringToValue() or IntToValue().
 107         Returns @true if value was different.
 108     */
 109     virtual bool GetValueFromControl( wxVariant& variant, wxPGProperty* property,
 110                                       wxWindow* ctrl ) const;
 111
 112     /** Sets value in control to unspecified. */
 113     virtual void SetValueToUnspecified( wxPGProperty* property,
 114                                         wxWindow* ctrl ) const = 0;
 115
 116     /**
 117         Called by property grid to set new appearance for the control.
 118         Default implementation  sets foreground colour, background colour,
 119         font, plus text for wxTextCtrl and wxComboCtrl.
 120
 121         The parameter @a appearance represents the new appearance to be applied.
 122
 123         The parameter @a oldAppearance is the previously applied appearance.
 124         Used to detect which control attributes need to be changed (e.g. so we only
 125         change background colour if really needed).
 126
 127         Finally, the parameter @a unspecified if @true tells this function that
 128         the new appearance represents an unspecified property value.
 129     */
 130     virtual void SetControlAppearance( wxPropertyGrid* pg,
 131                                        wxPGProperty* property,
 132                                        wxWindow* ctrl,
 133                                        const wxPGCell& appearance,
 134                                        const wxPGCell& oldAppearance,
 135                                        bool unspecified ) const;
 136
 137     /** Sets control's value specifically from string. */
 138     virtual void SetControlStringValue( wxPGProperty* property,
 139                                         wxWindow* ctrl, const wxString& txt ) const;
 140
 141     /** Sets control's value specifically from int (applies to choice etc.). */
 142     virtual void SetControlIntValue( wxPGProperty* property,
 143                                      wxWindow* ctrl, int value ) const;
 144
 145     /**
 146         Inserts item to existing control. Index -1 means end of list.
 147         Default implementation does nothing. Returns index of item added.
 148     */
 149     virtual int InsertItem( wxWindow* ctrl, const wxString& label, int index ) const;
 150
 151     /**
 152         Deletes item from existing control.
 153         Default implementation does nothing.
 154     */
 155     virtual void DeleteItem( wxWindow* ctrl, int index ) const;
 156
 157     /**
 158         Extra processing when control gains focus.
 159         For example, wxTextCtrl based controls should select all text.
 160     */
 161     virtual void OnFocus( wxPGProperty* property, wxWindow* wnd ) const;
 162
 163     /**
 164         Returns @true if control itself can contain the custom image.
 165         Default implementation returns @false.
 166     */
 167     virtual bool CanContainCustomImage() const;
 168 };
 169
 170
 171
 172 /**
 173     @class wxPGMultiButton
 174
 175     This class can be used to have multiple buttons in a property editor.
 176     You will need to create a new property editor class, override CreateControls,
 177     and have it return wxPGMultiButton instance in wxPGWindowList::SetSecondary().
 178
 179     For instance, here we add three buttons to a TextCtrl editor:
 180
 181     @code
 182     #include <wx/propgrid/editors.h>
 183
 184     class wxSampleMultiButtonEditor : public wxPGTextCtrlEditor
 185     {
 186         wxDECLARE_DYNAMIC_CLASS(wxSampleMultiButtonEditor);
 187
 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     wxIMPLEMENT_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_BUTTON )
 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